Skip to content
WunderUI

Spinner

Free

Show that something is loading when you cannot say how long it will take.

npx wunderui-cli add spinner

Playground

Installation

bash
npx wunderui-cli add spinner

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

Then use it:

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

export function SavingStatus() {
  return (
    <p role="status" className="flex items-center gap-2 text-sm text-text-secondary">
      <Spinner aria-hidden />
      Saving changes
    </p>
  )
}

Expected result: You see a small grey loader icon turning beside the text Saving changes.

When to use

Use Spinner for

  • A short wait on an action, such as saving, syncing or refreshing, where the length is not known
  • A status line or a row that shows a job is running
  • A panel with no layout to show yet, such as a dashboard that is loading its first data

Use something else for

  • Skeleton for content with a known layout that loads, such as a table, a list or a card
  • Progress for a task that reports how far it has come, such as an upload
  • Button for the wait after pressing a button, since its pending state draws the spinner for you

Placement

Put the spinner where the wait is: beside the line that names it, in the middle of a panel with nothing to show yet, or over content being refreshed.

Syncing 3 files

Name

A spinner is a status named Loading. On its own, give it a name that says what is loading; beside visible text, hide the spinner and let the text be the status.

Behavior and motion

What the spinner does with size, colour, motion and assistive technology.

Size
The icon is 16 px by default. Set another size with a class such as 24 or 32 px, which wins because it is applied after the default.
Colour
The icon is muted by default. Set the brand colour or any other text colour, and the stroke follows it, so there is one colour and no fill.
Accessibility
The icon is a status labelled Loading, which is announced politely when it appears. Pass an aria-label for a specific name, or hide it when a text beside it says what is loading.
Layout
The icon takes its size from the class and nothing else: no margin, no label, no container. Place it in a flex row with a small gap beside a text.
Motion
The icon turns once a second without end. It only rotates, through a transform.
Reduced motion
With reduced motion the icon does not turn. It stays on screen as a still loader and keeps its status role, so the state is still announced.

Anatomy

The Spinner is one element: a loader icon that turns. The figure marks it, and size and colour come from classes.

  • data-slot="spinner"

    A Lucide loader icon that turns once a second, 16 px and muted by default, announced as Loading. Pass an aria-label to say what is loading, or hide it when a visible text already does.

Best practices

  • Do

    When the spinner stands alone, pass a specific aria-label such as Saving changes. The default Loading says nothing about what is happening.

  • Do

    Beside a visible text, hide the spinner from screen readers and make the text a status, so the change is announced once, not twice.

  • Do

    Match the size to its neighbours: 16 px for body text, 24 px for a row icon, 32 px for a panel. Use the primary colour for a wait the person started, and keep the muted default for background work.

  • Do

    Keep the space the spinner takes when it goes away, so the layout doesn't move. Give its row a fixed height or swap in an icon of the same size.

  • Don’t

    Don't put a Spinner inside a Button. A button has a pending state that draws the spinner, keeps its width and blocks a second press.

  • Don’t

    Don't swap a chart or list for a Spinner while it loads, because the area collapses and the layout jumps. Use a Skeleton of the same size.

  • Don’t

    Don't use a Spinner when you know how far along the task is. Show a Progress bar, so people can tell whether it is worth waiting.

API reference

Spinner has no props of its own. It takes every prop of the svg it renders, such as className, aria-label, aria-hidden and role.

A Lucide loader icon that turns once a second, 16 px and muted by default, announced as Loading. Pass an aria-label to say what is loading, or hide it when a visible text already does.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("spinner")
Installnpx wunderui-cli add spinner

The full library index for assistants is at /llms.txt.