Feedback and status

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>
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.

Canonical

Minimal spinner

Rendered from the canonical pattern file.

Loading deployment history

HTML · Minimal spinner Raw HTML for HTML · Minimal spinner
<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

Scenario

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)

HTML · Activity finished Raw HTML for HTML · Activity finished
<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.

Scenario

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

HTML · Busy table region Raw HTML for HTML · Busy table region
<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.

Scenario

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

HTML · Beside the action that started it Raw HTML for HTML · Beside the action that started it
<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 example

Mobile long label

A spinner with a long, specific label at phone width.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.
HTML · Mobile long label Raw HTML for HTML · Mobile long label
<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.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
rolep.forma-spinnerstatus—Polite live region. Changes to the label are announced.
aria-hidden.forma-spinner__indicatortrue—Hides the decorative ring.
aria-busythe region being updatedtrue | false—Optional. Marks the container whose content is being replaced while the spinner runs.
disabledbuttonboolean—Optional. Prevents re-triggering the action that started the activity.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-spinnerBlock 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__indicatorElement 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.
Keyboard interaction
KeysResult
—The spinner is not focusable and has no keyboard interaction. Any Cancel or Retry control is a separate native button.
Events
EventDescription
—None. The application changes the label and data-forma-state when the activity changes.

Form behavior

Not a form control.

States

Spinner states
StateHow it is expressedPresentation
Activeno data-forma-state, or any value other than idleThe ring rotates once per 1000ms at constant speed.
Idledata-forma-state="idle"Rotation stops and the ring becomes a closed circle. Update the label to say what happened.
Reduced motionprefers-reduced-motion: reduceThe 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: reduce the 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.