Spinner

Use a spinner when a wait is short, indeterminate, and the user is expected to sit through it. If you know how far along the work is, show that instead — a progress bar answers "how much longer", which is the question a spinner cannot. If the wait replaces content the user was already reading, a Skeleton keeps the layout still and tells them what is coming back.

Base UI has no spinner primitive, so this is the one component in the library not built on one — there is no interaction to model and no state machine to get right. What is left is the part that is usually got wrong: announcing the wait once and correctly, and animating it in a way that survives prefers-reduced-motion.

Import

import { Spinner } from "@forte-ui/react";

Examples

Variants

The four are interchangeable. Each is laid out as a fraction of --forte-spinner-size and none of them overflows it, so swapping variant never moves anything beside the spinner — including in a row of mixed ones.

Which to pick is a question of voice:

Sizes

size sets the diameter — 1rem, 1.5rem or 2rem — and everything else is derived from it. The ring's stroke, the dots and their gaps, the bars and the halo all scale together, so a sm spinner is a smaller spinner rather than a thinner one.

The label scales too, dropping to --forte-font-size-1 at sm and rising to --forte-font-size-3 at lg.

Tones

tone picks the colour set. Four are semantic; current is the composable one — it takes currentColor, so a spinner dropped inside a button, a link or a status message matches the text around it and keeps matching it through hover, disabled and theme changes.

Label and placement

The indicator is aria-hidden, because a picture of motion is not information. label is the only thing that reaches a screen reader, and it is rendered whether or not it is visible — labelPlacement="hidden" keeps it in the accessibility tree and out of the paint.

Say what is being waited for. "Loading invoices" tells someone whether the wait concerns them; "Loading" makes them guess. Show the label outright once the wait is long enough that the user deserves to know what it is for — roughly a second is the usual threshold.

In a loading panel

The realistic case, and the one worth copying: the live region is the panel, and it is in the DOM from the first render. The spinner inside it is decorative, so there is exactly one announcement for one wait.

Reduced motion

Every variant keeps working under prefers-reduced-motion: reduce, and each one gets there differently. The two columns below are running side by side on the same page — the right-hand one carries data-forte-motion="reduce".

• ring stops rotating: --forte-spin-turn collapses to 0turn. A second animation that is always running — and is a no-op at full motion, because --forte-pulse-dip is 1 there — takes over as a slow opacity breathe.
• dots stop hopping: the hop is a --forte-travel-* token, so it goes to 0px. The staggered opacity wave is untouched and carries the whole thing.
• bars do not change at all. Nothing about them ever moved — the sense of rotation is entirely in the phase offset between eight fading spokes. That is what makes this the variant to choose when a spinner has to animate identically for everyone.
• pulse stops expanding and cross-fades in place. The second halo is faded out entirely, which is not tidiness: the two haloes are distinguishable only by radius, and frozen at the same radius they would cross-fade in antiphase into a ring of near-constant opacity that reads as nothing happening. --forte-motion-off — which is always 1 - --forte-motion-ok — is what removes it.

Theming

Accessibility

The root renders a <span role="status">, which carries an implicit aria-live="polite" and aria-atomic="true". The indicator and all its parts are aria-hidden; the label is the entire accessible name.

decorative removes the role and the hidden label. It deliberately does not add aria-hidden to the root, so a label you asked to show stays in the accessibility tree as ordinary text — visible text that assistive technology cannot reach is a bug in its own right, not a feature of a decorative flag.

Under forced colours the dots, bars and halo fill with currentColor, which the UA remaps to CanvasText along with the rest of the page. The ring is the exception and needs help: forced colours remaps background-color, color and border-color but leaves background-image alone, so the conic gradient would keep its brand hue against a system-coloured page — and can vanish outright on a dark system theme. The a11y layer drops the gradient there and redraws the ring as a CanvasText border with one edge painted Canvas. The gap has to be an explicit system colour rather than transparent, which forced colours does not preserve either; a fully coloured ring looks static however fast it turns.

The dimmed dots and bars keep their partial opacity under forced colours, which elsewhere in the library is a trap — opacity is one of the few properties forced colours does not override, so a 55% disabled control keeps full contrast and still reads as enabled. Here it is the mechanism rather than a bug: those parts are mid-animation, not disabled, and every one of them reaches full opacity in turn.

There is nothing to focus and nothing to press, so a spinner is not in the tab order and takes cursor: default per the pointer rules.

Theming

Every visual decision is a custom property declared on the spinner root. Set them on the spinner itself — through className or an inline style — rather than on an ancestor: the component declares its own defaults on the root element, and an element's own declaration beats an inherited value.

Two more values are written by the component rather than by you, and are listed here only so a var() typo is recognisable: --forte-spinner-count is the number of animated children the current variant renders, set on the root, and --forte-spinner-i is a child's index, set on each part. Every piece of per-child geometry is derived from the pair — a bar's angle is i / count of a turn, a dot's stagger is a fraction of the cycle — which is why the stylesheet needs no nth-child chain and why the bar count can be changed in one place.

Circles in this component use a literal 50% rather than var(--forte-radius-full), so data-forte-radius="none" cannot square off the ring, the dots or the halo — round is what those shapes are, not how they are styled. That is the same test Radio and the Button spinner apply, and the only grounds on which anything in the library opts out of the radius presets. The bars' end caps do follow the preset, because a squared-off spoke is a legitimate look.

API reference

Anything a <span> accepts passes through as well, including id, style and data-*.