An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file Spinner.tsx
* @input Uses React, i18n (useComponentTranslator), StyleX, SVG rendering
* @output Exports Spinner component, SpinnerProps, SpinnerSize, SpinnerShade types
* @position Core implementation of spinner loading indicator
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Spinner/Spinner.doc.mjs
* - /packages/core/src/Spinner/Spinner.test.tsx and __tests__/SpinnerMotion.a11y.chromium.spec.ts (rotor timing)
* - /packages/core/src/Spinner/index.ts
* - /apps/storybook/stories/Spinner.stories.tsx
* - /packages/cli/assets/templates/blocks/components/Spinner/ (showcase blocks)
*/
import {use, useId, useMemo, useRef, type ReactNode} from 'react';
import {SpinnerOwnerContext} from './SpinnerOwnerContext';
import * as stylex from '@stylexjs/stylex';
import {colorVars, spacingVars} from '../theme/tokens.stylex';
import type {BaseProps} from '../BaseProps';
import {Text} from '../Text/Text';
import {mergeProps} from '../utils/mergeProps';
import {mergeRefs} from '../utils/mergeRefs';
import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
import {themeProps} from '../utils/themeProps';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Spinner/Spinner.generated';
import {spinnerRotorStyles, syncRotationPhase} from './spinnerRotor';
registerEnglishFallback(english);
// =============================================================================
// Constants
// =============================================================================
/**
* The fraction of the ring the arc covers: SPINNER_ARC_FRACTION. StyleX reads
* only a literal in this file, and a test pins the two together.
*
* Themeable via `--spinner-arc-fraction`, declared alongside the other public
* vars in `sizeStyles` below. Only the inline `strokeDasharray` attribute
* (the pre-stylesheet render) still reads the constant directly; the CSS side
* composes the dash from the live var.
*/
const ARC_FRACTION = 0.375;
const PI = 3.141592653589793;
const SIZES = {
sm: {diameter: 10, border: 2},
md: {diameter: 14, border: 3},
lg: {diameter: 18, border: 3},
xl: {diameter: 28, border: 4},
};
/**
* Opacity the track is drawn at, per shade. `77 / 255` is the `4D` the onMedia
* track used to append to the token's hex — the same composite, but applied as
* `stroke-opacity` to a color off the cascade, so it no longer depends on the
* token being hex notation and it applies to a themed color too.
*/
const TRACK_OPACITY: Record<SpinnerShade, number> = {
default: 1,
subtle: 1,
onMedia: 77 / 255,
inherit: 0.3,
};
/**
* Where the resolved geometry lands: the public var, resolved into a registered
* `<length>` the `calc()`s below can do arithmetic on. The box and the ring
* read these; the public vars are declared once, on the element carrying the
* theme target, by `sizeStyles`.
*/
const RESOLVED_DIAMETER = '--_spinner-ring-diameter';
const RESOLVED_STROKE = '--_spinner-ring-stroke';
const RESOLVED_GEOMETRY_VARS = [RESOLVED_DIAMETER, RESOLVED_STROKE];
/**
* The composed box size: diameter plus a stroke width on each side.
*
* It is deliberately NOT registered, unlike the pair above. The element reads
* it through an inline `width`/`height` with the size's own default as the
* `var()` fallback, so a render with no stylesheet — where nothing declares
* it — still sizes the box the way it always did. A registered property always
* has a value (its `initial-value`), which would swallow that fallback and
* collapse the box to zero.
*/
const BOX_SIZE = '--_spinner-box-size';
/**
* Register the resolved geometry vars as `<length>`.
*
* Both are consumed inside `calc()` — the box adds two stroke widths to a diameter,
* the circle halves one. Unregistered, a custom property substitutes as text,
* so whatever a theme wrote lands in the expression verbatim and a bare `0`
* (a valid length on its own, a `<number>` inside `calc()`) poisons the sum:
* `calc(28px + 0 * 2)` is invalid at computed-value time and the box loses its
* size. Registered, the value is already an absolute length by the time the
* `calc()` sees it, so `0` means `0px` — a zero-width stroke that paints
* nothing — rather than a bare `0` that invalidates the sum and leaves the box
* with no size at all. One `stroke-width` drives both circles, so a themed
* stroke width of `0` hides the arc along with the track; an arc with no track behind
* it is `--spinner-track-color: transparent`.
*
* Only these private vars are registered. The four public ones deliberately
* are not: a registered property has an `initial-value`, so every element in
* the document would report a value for it — and
* `.github/scripts/theme-var-reachability.js` finds a var's declaring element
* by exactly that test, so registering them would point the guard at `<html>`
* and report a var no theme can select.
*/
function registerSpinnerVars(): void {
if (
typeof CSS === 'undefined' ||
typeof CSS.registerProperty !== 'function'
) {
return;
}
for (const name of RESOLVED_GEOMETRY_VARS) {
try {
CSS.registerProperty({
name,
syntax: '<length>',
inherits: true,
initialValue: '0px',
});
} catch {
// Already registered — a second copy of the package on the page, or a
// fast-refresh re-evaluation. registerProperty throws rather than
// replacing, and the existing registration is this same one.
}
}
}
// Registering an inherited property with an `initial-value` invalidates style
// for the whole document, so this runs when the module is evaluated rather
// than when a spinner mounts. A spinner is the loading indicator: it mounts
// onto a page that is already rendered, with someone already waiting, and the
// recalc it triggers there is paid on the full tree. At import the tree is
// whatever has rendered so far, which for a bundle loaded in the head is
// nothing.
//
// It is safe at module scope in both directions. The `typeof CSS` guard above
// keeps it out of the server render, and tree-shaking cannot strip it from a
// build that renders a spinner: core's `sideEffects` allowlist does not name
// this file, so a bundle that never imports `Spinner` drops the module whole —
// registration and all, which is the outcome you want — while one that does
// import it keeps the module, and a bare call is not something a bundler may
// elide.
registerSpinnerVars();
// =============================================================================
// Styles
// =============================================================================
const styles = stylex.create({
wrapper: {
display: 'inline-flex',
flexDirection: 'column',
alignItems: 'center',
gap: spacingVars['--spacing-2'],
},
spinner: {
display: 'inline-grid',
placeItems: 'center',
verticalAlign: 'middle',
// The public geometry vars, resolved into the registered `<length>` pair
// the arithmetic below needs. Reading them here rather than in each
// `calc()` keeps one place where a themed value enters the component, and
// it is the span that reads them whether the theme target is the span or
// the wrapper — a custom property inherits either way.
[RESOLVED_DIAMETER]: 'var(--spinner-diameter)',
[RESOLVED_STROKE]: 'var(--spinner-stroke-width)',
// The size of the box, composed here and applied as an inline style at the
// element, so that the box and the drawn ring come from the same two vars
// and a themed size moves both together — without the sizing moving from
// an inline style to a rule, which would hand a caller's `style={{width}}`
// a precedence over the box that it has never had.
[BOX_SIZE]: `calc(var(${RESOLVED_DIAMETER}) + var(${RESOLVED_STROKE}) * 2)`,
// The box is the ring's size, and a host does not get to take that away.
//
// `overflow: hidden` used to sit here, carried over from the canvas ring
// this component no longer draws. It clipped nothing — the painted circle
// is inscribed in the box, so hiding and showing the overflow render
// byte-identical pixels at every size, every shade, the labelled case and
// every rotation angle. What it did do is remove the floor under this box:
// a flex item whose overflow is not `visible` has an automatic minimum
// size of zero, so a narrow flex host was free to compress the box while
// the ring kept drawing at the size its own attributes ask for, and then
// the clip cut the ring off at the box edge. Ordinary rows hit it — a
// spinner beside a label in a 140px row lost 4px of its ring, one beside a
// `flex: 1 0 100px` sibling lost half of it — with nothing reporting a
// problem, because a sliced ring still spins.
//
// `flex-shrink: 0` then states the invariant directly rather than leaving
// it to the automatic minimum size, which a host takes away again the
// moment it sets `min-width: 0` on its items. A spinner that does not fit
// overflows its host visibly instead of being silently sliced.
flexShrink: 0,
},
ring: {
backfaceVisibility: 'hidden',
display: 'block',
// The track and the rotor share the one grid cell, stacked and centred.
gridArea: '1 / 1',
// The frame is the box, read from the same composed var the span is sized
// from — not from the size constant, which a theme cannot reach, and not
// from a percentage, which needs the grid area to be a definite size in
// both axes (an unresolved percentage height on an SVG falls back to the
// replaced-element default of 150px and drops the ring below the box).
// One expression, one source of truth, resolves in any layout.
width: `var(${BOX_SIZE})`,
height: `var(${BOX_SIZE})`,
// The svg is sized in CSS (100% of the span) rather than from the size
// constant, so one user unit is one CSS pixel AND the frame follows a
// themed diameter: the span's box is `diameter + 2 x stroke`, both public
// vars, so ring and frame move together. Sizing it from the constant
// instead left the svg larger than the box the moment a theme changed the
// diameter — an overflowing grid item aligns to start rather than centre,
// which put the ring 1.5-3.3px off across the four sizes.
overflow: 'visible',
},
// The rotor is the frame's size, so it turns about the ring's centre.
rotor: {
display: 'block',
gridArea: '1 / 1',
width: `var(${BOX_SIZE})`,
height: `var(${BOX_SIZE})`,
},
circle: {
fill: 'none',
// The ring is centred on the box (cx/cy 50%), so the arc's start offset
// pivots there too — as a CSS transform, since the SVG `transform`
// attribute would need that centre as a number in user units.
transformBox: 'fill-box',
transformOrigin: 'center',
strokeLinecap: 'round',
// The geometry the ring is actually drawn at. `r` and `stroke-width` are
// CSS properties on an SVG shape, and a CSS declaration outranks the
// presentation attribute of the same name — so the attributes below stay
// as the size's default (and as what a server render and a no-CSS render
// draw), and these take over the moment the cascade has a themed value.
r: `calc(var(${RESOLVED_DIAMETER}) / 2)`,
strokeWidth: `var(${RESOLVED_STROKE})`,
},
// The two ring colors ride `stroke` directly, read off the public vars the
// shade declares. The paint comes from the cascade, so every notation a
// theme can write — `var()`, `color-mix()`, and the `currentColor` the
// inherit shade is built on — resolves where it is used, and a color changed
// after mount repaints instead of going stale.
//
// The dash pattern is composed from the resolved diameter the same way, so a
// themed ring keeps the same fraction of arc rather than the same absolute
// dash. `pathLength` would be the shorter route to that, but it rescales the
// pattern against the path length the UA measures on its own approximation
// of the circle — 87.398 against the 87.965 of pi x 28 — which shortens the
// default arc by 0.64% and moves the cap by half a pixel. Composing the
// lengths keeps the default byte-identical to what it drew before.
//
// The fraction itself also rides a public var (`--spinner-arc-fraction`),
// unregistered like the other three color/geometry public vars — it is
// read as a bare `<number>` multiplier here, never summed with a unitless
// `0` the way the registered length pair guards against, so it needs no
// registration.
arc: {
stroke: 'var(--spinner-color)',
transform: 'rotate(-90deg)',
strokeDasharray: `calc(var(${RESOLVED_DIAMETER}) * ${PI} * var(--spinner-arc-fraction)) calc(var(${RESOLVED_DIAMETER}) * ${PI} * (1 - var(--spinner-arc-fraction)))`,
},
track: {stroke: 'var(--spinner-track-color)'},
});
// What each named `size` and `shade` resolve to. Both groups DECLARE the four
// public vars, on the element that carries the `spinner` theme target, and
// everything downstream reads them — so a theme's `@layer astryx-theme` rule
// against `.astryx-spinner[data-size="xl"]` overrides the default the same way it does for
// `--tree-list-indent` or `--button-focus-offset`, e.g.
// spinner: { 'size:xl': { '--spinner-diameter': '40px' } }.
//
// Declaring is only safe because #5410 moved the compiled StyleX CSS inside
// `@layer astryx-base`. Before it, StyleX emitted custom-property
// declarations at priority 0 and therefore OUTSIDE its layers, and an
// unlayered declaration beats every layer — so a StyleX-declared
// `--spinner-diameter: 10px` shadowed the theme's own rule no matter how
// specific the theme got. An earlier revision of this component worked around
// that by never declaring the public var and reading it with the default as a
// `var()` fallback; that is no longer necessary, and the fallback shape has a
// cost of its own — with nothing declaring the var,
// `theme-var-reachability.js` cannot find an element to check, so a documented
// var reads as unreachable.
// Arc fraction is not itself size-dependent, but it declares alongside the
// two vars that are, on the same per-size condition (`!hasLabel` gate at the
// call site) — it needs a home on whichever element carries the theme
// target, and this is the object already wired to be there.
const sizeStyles = stylex.create({
sm: {
'--spinner-diameter': `${SIZES.sm.diameter}px`,
'--spinner-stroke-width': `${SIZES.sm.border}px`,
'--spinner-arc-fraction': `${ARC_FRACTION}`,
},
md: {
'--spinner-diameter': `${SIZES.md.diameter}px`,
'--spinner-stroke-width': `${SIZES.md.border}px`,
'--spinner-arc-fraction': `${ARC_FRACTION}`,
},
lg: {
'--spinner-diameter': `${SIZES.lg.diameter}px`,
'--spinner-stroke-width': `${SIZES.lg.border}px`,
'--spinner-arc-fraction': `${ARC_FRACTION}`,
},
xl: {
'--spinner-diameter': `${SIZES.xl.diameter}px`,
'--spinner-stroke-width': `${SIZES.xl.border}px`,
'--spinner-arc-fraction': `${ARC_FRACTION}`,
},
});
const shadeStyles = stylex.create({
default: {
'--spinner-color': colorVars['--color-accent'],
'--spinner-track-color': colorVars['--color-track'],
},
subtle: {
'--spinner-color': colorVars['--color-text-secondary'],
'--spinner-track-color': colorVars['--color-track'],
},
onMedia: {
'--spinner-color': colorVars['--color-on-dark'],
'--spinner-track-color': colorVars['--color-on-dark'],
},
inherit: {
'--spinner-color': 'currentColor',
'--spinner-track-color': 'currentColor',
},
});
// The track's alpha is a property, not a color: it composites over whatever
// color the shade or the theme supplies. `77 / 255` is the `4D` the onMedia
// token's hex used to carry.
const trackOpacityStyles = stylex.create({
default: {strokeOpacity: TRACK_OPACITY.default},
subtle: {strokeOpacity: TRACK_OPACITY.subtle},
onMedia: {strokeOpacity: TRACK_OPACITY.onMedia},
inherit: {strokeOpacity: TRACK_OPACITY.inherit},
});
// =============================================================================
// Types
// =============================================================================
export type SpinnerSize = keyof typeof SIZES;
export type SpinnerShade = 'default' | 'onMedia' | 'subtle' | 'inherit';
export interface SpinnerProps extends BaseProps<HTMLSpanElement> {
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLSpanElement>;
/**
* Spinner size. The diameter is the ring itself; the rendered box adds the
* stroke width on each side (xl draws a 28px ring in a 36px box). A theme can
* redefine what each named size resolves to — see `--spinner-diameter`.
* - 'sm': 10px diameter
* - 'md': 14px diameter
* - 'lg': 18px diameter
* - 'xl': 28px diameter
* @default 'md'
*/
size?: SpinnerSize;
/**
* Color shade.
* - 'default': accent color on light backgrounds
* - 'onMedia': white on dark/accent backgrounds
* - 'subtle': secondary text color, less prominent — for inline use in lists
* - 'inherit': inherits the parent's `currentColor` (with a translucent
* track) — use inside colored elements like buttons so the ring matches
* the resolved foreground regardless of theme/variant
* @default 'default'
*/
shade?: SpinnerShade;
/**
* Visible content displayed below the spinner.
* Accepts a string or ReactNode for rich content.
*
* When `label` is a string, the visible text also provides the accessible
* name of the progressbar (via aria-labelledby, avoiding a duplicate
* announcement) unless `aria-label` is explicitly set.
*
* @example
* ```
* <Spinner label="Loading..." />
* <Spinner label={<><strong>Fetching data</strong><br/>This may take a moment</>} aria-label="Fetching data" />
* ```
*/
label?: ReactNode;
/**
* Test ID for the root element.
*/
'data-testid'?: string;
}
// =============================================================================
// Component
// =============================================================================
/**
* An animated loading indicator. Available in four sizes and four color shades.
*
* @example
* ```
* <Spinner />
* <Spinner size="sm" />
* <Spinner size="lg" shade="onMedia" />
* <Spinner label="Loading..." />
* <Spinner aria-label="Loading data" />
* ```
*/
export function Spinner({
size = 'md',
shade = 'default',
label,
xstyle,
className,
style,
'aria-label': ariaLabel,
'data-testid': testId,
ref,
...restProps
}: SpinnerProps) {
const {border, diameter} = SIZES[size];
const frameSize = diameter + border * 2;
const circumference = Math.PI * diameter;
const arcLength = circumference * ARC_FRACTION;
const hasLabel = label != null;
const labelId = useId();
const t = useComponentTranslator();
const spinnerRef = useRef<HTMLSpanElement>(null);
const rootRef = useMemo(() => mergeRefs(spinnerRef, ref), [ref]);
// When a visible string label renders (and no explicit aria-label is set),
// name the progressbar from the visible Text via aria-labelledby instead
// of duplicating the same string as aria-label — the duplicate would be
// announced twice by screen readers (WCAG 4.1.2).
const namedByVisibleLabel =
hasLabel && typeof label === 'string' && ariaLabel == null;
// Resolve accessible name: explicit aria-label > string label > the
// localized default. The fallback is AT-facing text, so it goes through the
// translation runtime like visible text does.
const resolvedAriaLabel =
ariaLabel ??
(typeof label === 'string' ? label : undefined) ??
t('@astryx.spinner.loading');
// Only a standalone Spinner announces. A Core component that composes it
// owns the task and silences it through the internal SpinnerOwnerContext;
// app code hides it with `aria-hidden`. A caller `role` other than
// progressbar also keeps it silent, as it shipped, so app code that
// silenced a composed ring that way keeps working; new code uses
// `aria-hidden`.
const isComposedInOwner = use(SpinnerOwnerContext);
const isHidden =
restProps['aria-hidden'] === true || restProps['aria-hidden'] === 'true';
const callerRole = restProps.role;
const hasShippedSilentRole =
callerRole != null && callerRole !== 'progressbar';
useAnnounceRenderedText(
spinnerRef,
!isComposedInOwner && !isHidden && !hasShippedSilentRole,
'',
{
skipFirstRender: true,
fallbackText: resolvedAriaLabel,
},
);
const spinner = (
<span
ref={hasLabel ? undefined : rootRef}
// An indeterminate progress indicator, so no aria-valuenow.
role="progressbar"
aria-label={namedByVisibleLabel ? undefined : resolvedAriaLabel}
aria-labelledby={namedByVisibleLabel ? labelId : undefined}
data-testid={hasLabel ? undefined : testId}
{...(hasLabel ? {} : restProps)}
{...mergeProps(
hasLabel ? '' : themeProps('spinner', {size, shade}),
stylex.props(
styles.spinner,
// The defaults are declared on whichever element carries the theme
// target, and only there: when a label moves the target to the
// wrapper, this span must inherit the wrapper's value rather than
// declare its own, which would shadow a theme's override with the
// default it is trying to replace.
!hasLabel && sizeStyles[size],
!hasLabel && shadeStyles[shade],
!hasLabel && xstyle,
),
hasLabel ? undefined : className,
// The box is sized here, after the caller's `style`, exactly as it was
// before the geometry became themeable: the component's own size wins
// over a `style={{width}}` a caller passes, and the precedence between
// the two is unchanged by this PR. What the value is made of has
// changed — it is the composed var rather than a number — so a themed
// diameter moves the box with the ring. The fallback is the size's own
// frame, for the render where no stylesheet has declared the var.
{
...(hasLabel ? {} : style),
width: `var(${BOX_SIZE}, ${frameSize}px)`,
height: `var(${BOX_SIZE}, ${frameSize}px)`,
},
)}>
{/* The track is zero-sized by attribute. With no stylesheet, the
rotor's arc alone fills the box, instead of two discs side by side.
`ring` sizes both to the box. */}
<svg
width={0}
height={0}
aria-hidden="true"
{...stylex.props(styles.ring)}>
<circle
cx="50%"
cy="50%"
r={diameter / 2}
strokeWidth={border}
{...stylex.props(
styles.circle,
styles.track,
trackOpacityStyles[shade],
)}
/>
</svg>
<span
ref={syncRotationPhase}
aria-hidden="true"
{...stylex.props(styles.rotor, spinnerRotorStyles.turn)}>
<svg
width={frameSize}
height={frameSize}
{...stylex.props(styles.ring)}>
<circle
cx="50%"
cy="50%"
r={diameter / 2}
strokeWidth={border}
// The size's own dash, for the render with no stylesheet. The rule
// above composes the same lengths from the resolved diameter, so a
// themed ring keeps this fraction of arc rather than this length.
strokeDasharray={`${arcLength} ${circumference - arcLength}`}
{...stylex.props(styles.circle, styles.arc)}
/>
</svg>
</span>
</span>
);
if (!hasLabel) {
return spinner;
}
return (
<div
ref={rootRef}
data-testid={testId}
{...restProps}
{...mergeProps(
themeProps('spinner', {size, shade}),
stylex.props(
styles.wrapper,
sizeStyles[size],
shadeStyles[shade],
xstyle,
),
className,
style,
)}>
{spinner}
{typeof label === 'string' ? (
<Text id={labelId} type="body" weight="bold">
{label}
</Text>
) : (
label
)}
</div>
);
}
Spinner.displayName = 'Spinner';