Loading deployment history
Spinner
<forma-spinner>
Indeterminate activity with a visible label: constant-velocity cadence that stops when the application marks the activity idle, static under reduced motion.
- Authoring tag
<forma-spinner>- Category
- Feedback and status
- Behavior owner
- Application state
- Canonical source
patterns/spinner.html
Purpose
A spinner says that something specific is happening and that its duration is not known. Forma renders a role="status" element containing a decorative rotating ring and a visible text label; the label is the real indicator and the ring is supporting presentation. The application owns the activity: it renders the spinner while work runs, updates the label, and sets data-forma-state="idle" (or removes the spinner) when the work stops.
Use when
- An operation is running and neither its total nor its progress is known.
- A region is waiting for a response and the wait is expected to be short.
- The user needs to know which operation is in progress, not just that something is.
Avoid when
- The application knows how much has been done: use Progress bar with a value.
- The layout of the incoming content is known and large: use Skeleton to hold its shape.
- The operation's outcome is uncertain or it needs reconciliation after a timeout: use Operation status.
Behavior to know
- The ring rotates at one named cadence (
--forma-motion-cadence-rotation-period, 1000ms) with linear timing; speed never encodes importance or expected completion time. - The rotation stops when
data-forma-state="idle"is set, and the ring closes to a full circle. - The label is always visible text; the ring is
aria-hidden.
Basic example
The smallest correct markup: the canonical pattern from patterns/spinner.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal spinner
Rendered from the canonical pattern file.
Loading deployment history
<forma-spinner class="forma-component-tag">
<p class="forma-spinner" role="status">
<span class="forma-spinner__indicator" aria-hidden="true"></span>
<span class="forma-spinner__label">Loading deployment history</span>
</p>
</forma-spinner>
Click or tap the code once to select all of it, then copy.
Examples
Activity finished
The same spinner after the application marks the activity idle. The ring stops and closes into a full circle, and the label is rewritten to report the result. Because the element stays in place, the status region announces the new text.
Deployment history loaded (42 entries)
<forma-spinner class="forma-component-tag">
<p class="forma-spinner" role="status" data-forma-state="idle">
<span class="forma-spinner__indicator" aria-hidden="true"></span>
<span>Deployment history loaded (42 entries)</span>
</p>
</forma-spinner>
Click or tap the code once to select all of it, then copy.
Busy table region
A results region marked aria-busy="true" while a new page loads, with the spinner as its visible status. The existing heading remains so users know which region is waiting.
Payments
Loading page 3 of payments
<forma-spinner class="forma-component-tag">
<section class="forma-stack" aria-labelledby="spinner-busy-region-title" aria-busy="true">
<h3 id="spinner-busy-region-title">Payments</h3>
<p class="forma-spinner" role="status">
<span class="forma-spinner__indicator" aria-hidden="true"></span>
<span>Loading page 3 of payments</span>
</p>
</section>
</forma-spinner>
Click or tap the code once to select all of it, then copy.
Beside the action that started it
A spinner placed next to the button that started a check. The button is natively disabled while the check runs so it cannot be triggered twice; the spinner label names the check.
Testing connection to the warehouse
<forma-spinner class="forma-component-tag">
<div class="forma-cluster">
<button type="button" disabled>Run connection test</button>
<p class="forma-spinner" role="status">
<span class="forma-spinner__indicator" aria-hidden="true"></span>
<span>Testing connection to the warehouse</span>
</p>
</div>
</forma-spinner>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Mobile long label
A spinner with a long, specific label at phone width.
What changes at narrow widths
- The spinner is inline-flex: the 1.25rem ring keeps its size and the label wraps beside it.
- The ring does not shrink as the label grows, so it stays a clear circle at 320px.
- Nothing scrolls horizontally; the spinner never exceeds its container width.
- The spinner has no touch target of its own; place any Cancel action as a separate button.
<forma-spinner class="forma-component-tag">
<p class="forma-spinner" role="status">
<span class="forma-spinner__indicator" aria-hidden="true"></span>
<span>Recalculating allocations for all 14 cost centers in the September close</span>
</p>
</forma-spinner>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
role | p.forma-spinner | status | — | Polite live region. Changes to the label are announced. |
aria-hidden | .forma-spinner__indicator | true | — | Hides the decorative ring. |
aria-busy | the region being updated | true | false | — | Optional. Marks the container whose content is being replaced while the spinner runs. |
disabled | button | boolean | — | Optional. Prevents re-triggering the action that started the activity. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-spinner | Block class | — | Root inline-flex row of ring and label. The label is a plain text span after the ring; it needs no class. |
.forma-spinner__indicator | Element class | — | Decorative 1.25rem ring with an open top edge that rotates while active. |
[data-forma-state] | Attribute hook | "idle" | Set to idle to stop the rotation and close the ring. Any other value, or no attribute, means active. |
| Keys | Result |
|---|---|
| — | The spinner is not focusable and has no keyboard interaction. Any Cancel or Retry control is a separate native button. |
| Event | Description |
|---|---|
— | None. The application changes the label and data-forma-state when the activity changes. |
Form behavior
Not a form control.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Active | no data-forma-state, or any value other than idle | The ring rotates once per 1000ms at constant speed. |
| Idle | data-forma-state="idle" | Rotation stops and the ring becomes a closed circle. Update the label to say what happened. |
| Reduced motion | prefers-reduced-motion: reduce | The ring is static with its open segment; the label and status role still identify the activity. |
Accessibility
Forma provides
- Keeps a visible text label as the primary indicator and hides the ring from assistive technology.
- Draws the ring in
currentColor, so it stays visible in forced colors. - Stops repeated motion when the activity stops and under reduced motion.
Your application supplies
- Write a label that names the operation ("Loading deployment history"), not just "Loading".
- Keep the same element in place while the activity continues; replacing it restarts the rotation and can read as new work.
- Update the label or remove the spinner when the activity ends, and report failures with an Alert or Operation status.
- Avoid many spinners at once in one view; they compete for attention and announcements.
Responsive behavior
- Inline-flex with a fixed 1.25rem ring; the label wraps in the remaining width.
- No breakpoints. The spinner fits inside toolbars, table cells and region headers.
- Use a Cluster to place it beside a related action so the pair wraps together.
Motion
- The ring rotates with
--forma-motion-cadence-rotation-period(1000ms) and linear easing, infinitely: constant-velocity cadence with no spring or bounce on each cycle. - Rotation runs only while the spinner is not idle. Setting
data-forma-state="idle"stops it immediately. - Changing the label text does not restart the cycle, because the same element keeps running its animation.
- Under
prefers-reduced-motion: reducethe animation is removed and the ring is static.
Usage guidance
Do
- Show a spinner only after a short delay for fast operations, so it does not flash.
- Pair long-running activity with a way to cancel when the application supports it.
Avoid
- Using a spinner as the only sign of what is happening.
- Speeding up or slowing down the ring to suggest urgency or remaining time.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.