Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
spinner · base base · style base-lyraOpen under the product theme

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.

Theme
Density
Text
Status
Accent theme
Accent
spinner-a-brief-wait · base base · style base-lyraOpen under the product theme
spinner-a-brief-wait.tsx
import { 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.

Theme
Density
Text
Status
Accent theme
Accent
spinner-two-sizes · base base · style base-lyraOpen under the product theme
spinner-two-sizes.tsx
import { 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 skeleton instead.
  • The wait belongs to a control performing its own action, such as a submit button saving a reading.Use button instead.
  • You can measure how far through a known sequence of steps the reader is, so the wait is determinate.Use stepper instead.

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.
KeyActionNotes
TabSkips the spinnerA spinner is status, not a control. Nothing here is focusable.
Shift+TabSkips the spinnerSame in reverse. A spinner never appears in the focus order.
Arrow keysNothingThere is nothing to select, move or expand. The spinner captures no key.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below 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.