Spinner

An animated loading spinner with Framer Motion rotation, multiple sizes and color variants, optional label text, and reduced-motion support.

Overview

The Spinner component provides an animated loading indicator for communicating in-progress states. It uses Framer Motion for smooth, GPU-accelerated rotation with automatic prefers-reduced-motion support. Includes 4 sizes, 4 color variants, optional label text, and proper role="status" semantics.

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add spinner

pnpm dlx @work-rjkashyap/unified-ui add spinner

npx @work-rjkashyap/unified-ui add spinner

bunx @work-rjkashyap/unified-ui add spinner

If you haven't initialized your project yet, run npx @work-rjkashyap/unified-ui init first. See the CLI docs for details.

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui

pnpm add @work-rjkashyap/unified-ui

yarn add @work-rjkashyap/unified-ui

bun add @work-rjkashyap/unified-ui

Anatomy

import { Spinner } from "@work-rjkashyap/unified-ui";

md (20px)

lg (24px)

Size	Diameter	Use Case
`xs`	14px	Inside buttons, badges, inline text
`sm`	16px	Table cells, small buttons, compact UI
`md`	20px	Default loading state
`lg`	24px	Empty states, page loading, hero areas

Variants

Default

Primary

Secondary

Muted

{/* Inherits current text color */}
<Spinner variant="default" />

{/* Uses brand/primary color */}
<Spinner variant="primary" />

{/* Uses foreground color */}
<Spinner variant="secondary" />

{/* Uses muted-foreground color */}
<Spinner variant="muted" />

{/* Inherits current text color */}<Spinner variant="default" />{/* Uses brand/primary color */}<Spinner variant="primary" />{/* Uses foreground color */}<Spinner variant="secondary" />{/* Uses muted-foreground color */}<Spinner variant="muted" />

With Label

Loading…

Fetching data…

Please wait…

<Spinner label="Loading…" />
<Spinner label="Fetching data…" variant="primary" />
<Spinner label="Please wait…" variant="muted" size="sm" />

<Spinner label="Loading…" /><Spinner label="Fetching data…" variant="primary" /><Spinner label="Please wait…" variant="muted" size="sm" />

Label Position

Inline label

right (default)

Stacked label

bottom

{/* Inline — label beside spinner */}
<Spinner label="Inline label" labelPosition="right" />

{/* Stacked — label below spinner */}
<Spinner label="Stacked label" labelPosition="bottom" />

{/* Inline — label beside spinner */}<Spinner label="Inline label" labelPosition="right" />{/* Stacked — label below spinner */}<Spinner label="Stacked label" labelPosition="bottom" />

In Context

Loading your dashboard…

Refreshing data…

{/* Inside a button */}
<Button disabled>
<Spinner size="xs" />
Saving…
</Button>

{/* Empty state / page loader */}
<div className="flex flex-col items-center gap-3 py-8">
<Spinner size="lg" variant="primary" />
<span className="text-sm text-muted-foreground">Loading your dashboard…</span>
</div>

{/* Inline status text */}
<div className="flex items-center gap-2 text-sm text-muted-foreground">
<Spinner size="xs" variant="muted" />
Refreshing data…
</div>

{/* Inside a button */}<Button disabled><Spinner size="xs" />Saving…</Button>{/* Empty state / page loader */}<div className="flex flex-col items-center gap-3 py-8"><Spinner size="lg" variant="primary" /><span className="text-sm text-muted-foreground">Loading your dashboard…</span></div>{/* Inline status text */}<div className="flex items-center gap-2 text-sm text-muted-foreground"><Spinner size="xs" variant="muted" />Refreshing data…</div>

Custom Stroke Width

Thin (1.5)

Default (2.5)

Thick (4)

<Spinner size="lg" strokeWidth={1.5} />
<Spinner size="lg" strokeWidth={2.5} />  {/* default */}
<Spinner size="lg" strokeWidth={4} />

<Spinner size="lg" strokeWidth={1.5} /><Spinner size="lg" strokeWidth={2.5} />  {/* default */}<Spinner size="lg" strokeWidth={4} />

Props

Prop	Type	Default	Description
`size`	`"xs" \| "sm" \| "md" \| "lg"`	`"md"`	Size of the spinner.
`variant`	`"default" \| "primary" \| "secondary" \| "muted"`	`"default"`	Color variant.
`label`	`ReactNode`	—	Visible label text alongside the spinner.
`labelPosition`	`"right" \| "bottom"`	`"right"`	Position of the label relative to the spinner.
`strokeWidth`	`number`	`2.5`	Thickness of the spinner stroke.
`aria-label`	`string`	`"Loading"`	Accessible label for screen readers.
`className`	`string`	—	Additional CSS classes for the root element.

Accessibility

The Spinner includes a screen-reader-only fallback text that announces the loading state even when no visible label is present.

role="status" — Announces the loading state as a live region to screen readers.
aria-label — Defaults to "Loading" or the label prop if it's a string.
Screen-reader text — When no visible label is provided, a visually hidden <span className="sr-only"> is rendered for screen readers.
SVG is decorative — The spinner SVG uses aria-hidden="true" since the status text conveys meaning.
Reduced motion — Automatically detects prefers-reduced-motion via Framer Motion's useReducedMotion hook and falls back to CSS animate-spin which the browser can optimize or skip per OS settings.

Design Tokens

Token	Usage
`--primary`	Primary variant spinner color
`--foreground`	Secondary variant spinner color
`--muted-foreground`	Muted variant spinner/label color
`currentColor`	Default variant (inherits)