---
title: "Spinner"
description: "An indeterminate loading ring for a brief in-place wait whose shape is unknown, reached for only where a skeleton cannot say what is arriving."
url: "https://opsinjs.pensievelabs.org/docs/components/spinner"
source: "https://opsinjs.pensievelabs.org/docs/components/spinner.md"
section: "Components"
status: "shipped"
kind: "component"
category: "feedback"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["loader", "busy indicator", "activity indicator"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="spinner"
  status="shipped"
  questions="[
  &#x22;No contrast pair has been measured, so whether the muted ring clears the non-text floor on a card and on the page is argued rather than checked.&#x22;,
  &#x22;Nobody has heard the role=\&#x22;status\&#x22; region in a screen reader, so whether it announces the wait once by name, rather than twice, is untested.&#x22;,
  &#x22;Forced colours are unhandled, because the SVG stroke is left where the author set it, and whether the ring stays visible there is untested.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="spinner" unbuilt="false" importPath="@/components/ui/spinner" />

```tsx
import { Spinner } from "@/components/ui/spinner"
```

```tsx
<span className="inline-flex items-center gap-2 text-muted-foreground">
  <Spinner label="Loading your readings" />
  <span>Loading</span>
</span>
```

## Examples [#examples]

<ComponentPreview name="spinner" />

### A brief wait [#a-brief-wait]

A ring beside a visible word, for a wait with no known shape. `label` names the
wait for a screen reader while the visible caption carries it for everyone else.

<ComponentPreview name="spinner-a-brief-wait" kind="example" align="start" />

### Two sizes [#two-sizes]

`size` sets `sm` and `md` side by side. Each is measured in `em`, so the ring
grows with the surrounding text rather than pinning at a fixed size.

<ComponentPreview name="spinner-two-sizes" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;A brief in-place wait whose result has no known shape, so a skeleton would have no single outline to promise.&#x22;,
  &#x22;A spot too small to draw an outline in, such as a toolbar slot or a compact inline control.&#x22;,
  &#x22;A wait short enough that a skeleton would flash in and straight back out.&#x22;,
]"
  avoid="[
  { case: &#x22;The shape of what is arriving is known and can be drawn: a card, a list, a chart, a block of text.&#x22;, instead: &#x22;skeleton&#x22; },
  { case: &#x22;The wait belongs to a control performing its own action, such as a submit button saving a reading.&#x22;, instead: &#x22;button&#x22; },
  { case: &#x22;You can measure how far through a known sequence of steps the reader is, so the wait is determinate.&#x22;, instead: &#x22;stepper&#x22; },
]"
/>

## Accessibility [#accessibility]

The root carries a required `aria-label` plus a visually hidden text twin, and
the SVG ring is `aria-hidden`, so the decorative motion stays out of the
accessibility tree. Sizing is em based throughout with no `px` type step, and
the ring draws only in `currentColor`, with no status colour or category colour
of its own. Axe, target-size and 320px reflow checks were clean, and nothing
needed changing.

**Residual items.**

* The ring takes whatever ink colour the caller's context supplies rather than
  a colour the component sets itself, so its contrast against either theme's
  surfaces cannot be verified or hardened from source. That gap belongs to the
  report below.
* The missing-label warning is development only, so it does not stop a
  production caller passing an empty or whitespace `label`. `divider` and
  `segmented-control` follow the same convention.

<KeyboardTable
  name="spinner"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Skips the spinner&#x22;,
    notes: &#x22;A spinner is status, not a control. Nothing here is focusable.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Skips the spinner&#x22;,
    notes: &#x22;Same in reverse. A spinner never appears in the focus order.&#x22;,
  },
  {
    keys: &#x22;Arrow keys&#x22;,
    action: &#x22;Nothing&#x22;,
    notes: &#x22;There is nothing to select, move or expand. The spinner captures no key.&#x22;,
  },
]"
/>

<ContrastReport component="spinner" />

## Props interface [#props-interface]

<PropsTable name="SpinnerProps" />

`label` is required and has no default, because a guessed name would describe the
wrong wait. `size` defaults to `md` and chooses visual weight only. There is no
colour prop: colour reaches the ring only through `className`, and the
two-colour-axes rule applies to that class in full.
