Spinner

Animation Variants

Context Variants

Size Variants

Spinner Properties

Important: The delay prop. Always add a delay of 300–500ms before showing a spinner. If the operation completes within that window, the user never sees the spinner (which is ideal — flashing a spinner for 100ms is disorienting). This single prop eliminates the most common spinner UX problem.

Design Token Mappings

Spinners are visually simple but touch color, motion, and sizing tokens. For token architecture fundamentals, see the Design Tokens Complete Guide.

Spinner States

Spinners are stateless animations — they don't have hover, focus, or active states like interactive components. Their "state" is defined by their presence and context:

The Spinner Lifecycle

For the best user experience, follow this lifecycle:

1. Operation starts → Start delay timer (300ms)
2. Delay expires, still loading → Fade spinner in (150ms)
3. Operation completes → Fade spinner out (150ms) or morph to checkmark
4. Operation fails → Replace spinner with error state or Alert

This prevents flash-of-spinner and ensures smooth transitions. Preview fade animations with the Animation & Easing Tool.

Accessibility — Spinner

Spinners present a unique accessibility challenge: they're purely visual animations, so without proper ARIA semantics, screen reader users have no idea something is loading. Verify spinner visibility with the Contrast Checker.

ARIA Pattern

<!-- Standalone spinner with label -->
<div role="status" aria-label="Loading search results">
  <svg class="spinner" aria-hidden="true"><!-- animated ring --></svg>
  <span class="sr-only">Loading search results</span>
</div>

<!-- Content region with spinner -->
<div aria-busy="true" aria-describedby="loading-msg">
  <div role="status" id="loading-msg">
    <svg class="spinner" aria-hidden="true"></svg>
    Loading your dashboard…
  </div>
</div>

Key points:

• Use role="status" (implicit aria-live="polite") so the loading message is announced without interrupting the user
• Mark the SVG/animation as aria-hidden="true" — screen readers should read the text, not try to describe the animation
• Set aria-busy="true" on the container whose content is loading — this tells AT that the region is updating

WCAG Success Criteria

Motion Sensitivity

Some users experience motion sickness or distraction from continuous animations. Respect the prefers-reduced-motion media query:

@media (prefers-reduced-motion: reduce) {
  .spinner {
    animation: none;
    /* Show a static icon or pulsing opacity instead */
    opacity: 0.7;
  }
}

This is particularly important for large overlay spinners that dominate the viewport. WCAG 2.3.3 (Animation from Interactions, AAA) recommends this approach.

Do

• Always include a delay (300–500ms) before showing the spinner. If the operation is faster, the user never sees it — which is the ideal experience.
• Provide a text label whenever possible. "Loading" is better than nothing, but "Loading search results…" is better than "Loading."
• Use the smallest appropriate size. A button spinner should be xs/sm, not a massive lg spinner crammed into a 40px button.
• Set aria-busy="true" on the content region being loaded, not on the spinner itself.
• Respect prefers-reduced-motion. Replace continuous rotation with a gentle pulse or static indicator.
• Remove spinners completely when loading finishes — don't just hide them visually. Remove from DOM and accessibility tree.
• Use currentColor for the spinner color so it automatically adapts to its text context (dark text = dark spinner, light text = light spinner).

Don't

• Don't use a spinner when you have progress data. Use a Progress Bar.
• Don't use a spinner when you know the content shape. Use a Skeleton.
• Don't stack multiple spinners in the same view. One loading state per visible region. If the whole page is loading, use one overlay spinner or a skeleton screen.
• Don't use spinners for operations over 10 seconds without additional context. After 10 seconds, users wonder if something is broken. Add "This may take a few moments…" or switch to a progress bar.
• Don't block the entire page unless absolutely necessary. Prefer inline or section spinners that allow the user to interact with other parts of the UI.
• Don't animate at framerates that cause flashing. WCAG 2.3.1 prohibits content that flashes more than 3 times per second.
• Don't use a spinner as a permanent state. If loading fails, transition to an error state or Empty State.

Performance Considerations

Spinners should be lightweight:

• Prefer CSS animations over JavaScript-driven ones (CSS animations run on the compositor thread)
• Use transform: rotate() not border-color animations for GPU acceleration
• SVG spinners are resolution-independent and typically smaller than GIF/Lottie alternatives
• Explore optimized spinner patterns in the Loader Generator

Design System Implementations

Material Design 3 uses the CircularProgressIndicator component for both spinners and circular progress bars. In indeterminate mode, Material's animation is distinctive: the arc length oscillates between short and long while simultaneously rotating, creating a "breathing" effect that feels more organic than a simple rotation. Material also specifies exact animation curves: the rotation uses linear timing, while the arc sweep uses a custom cubic-bezier. This is a great example to study in the Animation & Easing Tool.

Apple's Human Interface Guidelines call this an "Activity Indicator." On iOS, it's the iconic set of 8 or 12 rounded bars arranged in a circle, each fading in sequence. This design is intentionally ambiguous about direction and speed — Apple's philosophy is that indeterminate loading should feel calm, not urgent. On macOS, the "spinning beach ball" cursor is the system-level equivalent (and universally dreaded).

Ant Design provides a Spin component that wraps content, automatically adding a blur/dim effect and centering the spinner over the wrapped region. It supports tip for label text, size (small/default/large), and a delay prop measured in milliseconds. The indicator prop lets you replace the default spinner with any custom animation — a useful escape hatch.

Chakra UI's Spinner is a styled <div> using border and border-top-color with a CSS rotation animation — the simplest possible implementation. It supports emptyColor (track), color (active arc), thickness, speed, and size. It uses role="status" with a visually hidden "Loading…" text for accessibility.

Shadcn/ui provides a minimal SVG-based spinner using Lucide's Loader2 icon with a CSS rotation animation. It's just an icon with animate-spin — about as simple as a spinner can get.

Bootstrap uses a border-based spinner (.spinner-border) and a "growing" variant (.spinner-grow) that pulses. It provides .spinner-border-sm for button contexts and uses role="status" with .visually-hidden text.

For custom spinner patterns with optimized CSS animations, explore the Loader Generator. Preview animation timing functions in the Animation & Easing Tool.