Spinner

Show that something's loading. Don't flash for fast loads.

import { Spinner } from '@dashforge/tw';

<Spinner />

Quick Start

<Spinner />                                    {/* default md, currentColor */}
<Spinner size="lg" color="primary" />          {/* large, indigo */}
<Spinner withTrack thickness="thick" />        {/* on busy bg */}
<Spinner delay={200} />                        {/* anti-flash: only shows after 200ms */}

Examples

Sizes

Five-step scale, mapping to Tailwind w-*/h-* classes:

import { Spinner, Stack } from '@dashforge/tw';

<Stack direction="row" gap={4} align="center">
  <Spinner size="xs" />
  <Spinner size="sm" />
  <Spinner size="md" />
  <Spinner size="lg" />
  <Spinner size="xl" />
</Stack>

Colors

Inherit currentColor (default) or pass an explicit semantic color:

import { Spinner, Stack } from '@dashforge/tw';

<Stack direction="row" gap={4} align="center">
  <Spinner color="primary" />
  <Spinner color="secondary" />
  <Spinner color="success" />
  <Spinner color="warning" />
  <Spinner color="danger" />
  <Spinner color="info" />
  <Spinner color="neutral" />
</Stack>

Inherit mode pairs naturally with text-color contexts (e.g. inside a button label). Explicit mode is for standalone callouts.

Thickness + track

Three thickness steps (thin / md / thick) plus the opt-in withTrack ghost ring at 20% opacity of currentColor (useful on busy backgrounds):

import { Spinner, Stack } from '@dashforge/tw';

<Stack direction="row" gap={4} align="center">
  <Spinner size="lg" color="primary" thickness="thin" />
  <Spinner size="lg" color="primary" thickness="md" />
  <Spinner size="lg" color="primary" thickness="thick" />
  <Spinner size="lg" color="primary" withTrack />
</Stack>

Anti-flash delay (Atlaskit-inspired)

For state changes where the loading window is often under 200ms (e.g. cached fetches), set delay to defer rendering. If the loading state resolves before the delay, the spinner never appears — no flicker.

<Spinner delay={200} />   {/* only renders after 200ms of loading */}

Pair with a loading state boolean:

function Refresh() {
  const [loading, setLoading] = useState(false);
  return (
    <Button onClick={async () => {
      setLoading(true);
      await refetch();
      setLoading(false);
    }}>
      Refresh {loading && <Spinner size="sm" delay={150} />}
    </Button>
  );
}

If refetch() completes in under 150 ms, the user never sees the spinner — even though the React tree mounted it.

Inside a Button (Sprint 4.4 DRY)

<Button> and <IconButton>'s loading prop now delegate to <Spinner> internally — no more two bespoke spinner glyphs in the catalog. You don't need to manually inject one:

<Button loading={isSaving}>Save</Button>
{/* Button internally renders <Spinner size="..." /> in the label slot */}

If you want to customize the spinner inside a button, use the slotProps of Button — that's the right composition point.

Decorative mode

Default a11y: Spinner ships with role="status" + aria-live="polite" + aria-label="Loading". Screen readers announce loading state on mount.

When the Spinner is inside a larger labeled region (e.g. a panel that already announces "Loading customer details"), the spinner's announce becomes duplicate noise. Pass label="" to suppress role/aria-live:

<section aria-busy="true" aria-label="Loading customer details">
  <Spinner label="" />        {/* decorative — no double announce */}
  <span>Loading customer details…</span>
</section>

Custom accessible label

<Spinner label="Refreshing transactions" />
{/* renders: role="status" aria-live="polite" aria-label="Refreshing transactions" */}

API

Props

Behaviors

• motion-reduce gate: the spinning animation respects prefers-reduced-motion. When the user has reduced motion enabled, the SVG sits static — the role/aria-live still announces loading, but no rotation.
• role precedence: when label === '' the component omits role/aria-live entirely (decorative mode). Otherwise both are present.

Notes

• No bridge integration (access/visibleWhen). Spinner is pure presentational — no state, no interactivity. If you need to hide a spinner conditionally, wrap it in a parent that has the bridge contract (e.g. <Box visibleWhen={...}>).
• Sprint 4.4 DRY refactor: this component replaced two bespoke SVG copies that lived inside <Button> and <IconButton>. Visual consistency across the catalog is now guaranteed by a single source.
• For page-level loaders with skeleton structure rather than rotating arc, use <Skeleton> instead.