Spinner
FreeShow that something is loading when you cannot say how long it will take.
npx wunderui-cli add spinnerPlayground
Installation
npx wunderui-cli add spinnerWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Spinner } from "@/components/ui/spinner"Then use it:
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
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.
Saving changes
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.
- 1data-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.
get_component("spinner")npx wunderui-cli add spinnerThe full library index for assistants is at /llms.txt.