Components
Spinner
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.
Usage
pnpm dlx shadcn@latest add @opsinjs/spinner
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Spinner } from "@/components/ui/spinner"<span className="inline-flex items-center gap-2 text-muted-foreground">
<Spinner label="Loading your readings" />
<span>Loading</span>
</span>Examples
spinner · base base · style base-lyraOpen under the product themeA 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.
spinner-a-brief-wait · base base · style base-lyraOpen under the product themeimport { Spinner } from "@/components/ui/spinner"
export default function SpinnerABriefWait() {
return (
<div className="flex w-full max-w-sm items-center justify-center rounded-opsin-lg border border-border px-opsin-6 py-opsin-8 text-muted-foreground">
<span className="inline-flex items-center gap-opsin-2">
<Spinner label="Loading" />
<span className="text-opsin-subheadline">Loading</span>
</span>
</div>
)
}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.
spinner-two-sizes · base base · style base-lyraOpen under the product themeimport { Spinner } from "@/components/ui/spinner"
export default function SpinnerTwoSizes() {
return (
<div className="flex items-center gap-opsin-4 text-muted-foreground">
<Spinner label="Loading" size="sm" />
<Spinner label="Loading" size="md" />
</div>
)
}When to use it
Use it when
- A brief in-place wait whose result has no known shape, so a skeleton would have no single outline to promise.
- A spot too small to draw an outline in, such as a toolbar slot or a compact inline control.
- A wait short enough that a skeleton would flash in and straight back out.
Do not use it when
- The shape of what is arriving is known and can be drawn: a card, a list, a chart, a block of text.Use
skeletoninstead. - The wait belongs to a control performing its own action, such as a submit button saving a reading.Use
buttoninstead. - You can measure how far through a known sequence of steps the reader is, so the wait is determinate.Use
stepperinstead.
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.dividerandsegmented-controlfollow the same convention.
| Key | Action | Notes |
|---|---|---|
| Tab | Skips the spinner | A spinner is status, not a control. Nothing here is focusable. |
| Shift+Tab | Skips the spinner | Same in reverse. A spinner never appears in the focus order. |
| Arrow keys | Nothing | There is nothing to select, move or expand. The spinner captures no key. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from SpinnerProps in registry/bases/base/spinner.tsx.
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.