Spinner
Spinner is an indeterminate loading indicator for work with no predictable duration. Without size it measures
1em, so it scales with the surrounding font and fits any slot that takes an Icon.Feedback & Loading
When to use
Use when
- A request or first load runs and you cannot estimate how long it takes.
- A button or icon slot must show that its action is in progress.
- You need a "next refresh in…" ring next to polled data (
variant="countdown").
Avoid when
- You know the percentage — use
ProgressBar. - The layout of the incoming content is known — use
Skeleton. - Nothing is loading. A spinner that never stops reads as a failure.
Usage
<Spinner />
<Spinner size={32} color="primary" />
<IconButton icon={<Spinner />} size="small" label="Loading" />size takes a number (px) or any CSS length. color takes a theme color and paints the arc.
IconButton swaps its icon for a Spinner while isLoading, and InputSelect shows one while loading options.
Countdown ring
variant="countdown" is determinate: the arc drains over duration (ms, default 15000) and refills whenever
cycle changes. Pass the last poll timestamp or a counter.
<Spinner variant="countdown" duration={15000} cycle={lastPollAt} color="primary" />Accessibility
- The default variant renders
role="status"; the countdown rendersrole="timer". labelis the accessible name (default'Carregando'). Localize it and say what is loading.- Keep one announcing spinner per loading region; several live regions at once become noise.
- When visible loading text sits next to it, pass
aria-hiddento avoid a duplicate announcement.
Properties
Name
Type
Default
Description
colorstringnoneTheme token (`theme.colors`) used as `color`. Has lower precedence than
`contrast`: when both are provided, the contrast calculation wins.
Stays `string` (not the typed union): `color` is also an HTML attribute
(`<li color>`, etc.) and interfaces extending native props require
identical types on the name collision.
containmentstringnoneContainment marker for the `cq` channel: emits
`container-type` (+ `container-name` when the string form carries one,
e.g. `'inline-size card'`). Apply on the immediate wrapper of the
adapting component — NEVER on page-level shells.
cyclestringnumbernoneRestart key for the countdown. Any change (a poll timestamp, a counter)
refills the ring and starts draining again. Ignored by the
indeterminate variant.
durationnumber15000Countdown length in milliseconds. Ignored by the indeterminate variant.
labelstring'Carregando'Accessible name announced by screen readers (`role="status"`, or
`role="timer"` for the countdown variant). Override it to localize or
to say WHAT is loading.
When the spinner is purely decorative — another visible, associated
loading text already exists nearby — pass `aria-hidden`.
legibility"on-photo"noneReading-shadow preset for text over a photographic background
(`on-photo`). Replaces the inline `style={{ textShadow }}` in the
consumer (brasil_2030 radar, gap A3). Token emission is deferred until a
2nd consumer asks for the raw var (see backlog).
lineClampnumbernoneCaps the text at this many lines and ends the cut with an ellipsis.
The full string stays in the DOM.
pageShellbooleannoneCenters the element and caps the width at `theme.layout.pageMaxWidth`.
The page shell of a classic centered layout.
readablenumberbooleannoneMakes the `color` legible against the page surface: `true` = WCAG AA
(4.5), a number sets a custom floor. Ignored with `contrast`.
See the Layout Props concept page for the full semantics.
sizestringnumbernoneSpinner size. Accepts a number (px) or a CSS string (`em`, `rem`, etc.).
When omitted, uses `1em` to inherit the context's `font-size` — so the
spinner stays naturally proportional wherever it is embedded.
transformstringnoneCSS `transform` value (e.g. `translate(-50%, -33px)`). Never leaks
to the DOM as an attribute.
variant"indeterminate""countdown"'indeterminate'`'indeterminate'` spins forever. `'countdown'` is a determinate ring
that drains over `duration` and stays empty until `cycle` changes.
Also accepts the layout props.