# Spinner

A spinning indicator for an in-progress loading state.

- Category: Core Elements
- Page: https://wunderui.com/components/spinner
- Tier: Free

## Install

```bash
npx wunderui-cli add spinner
```

## Import

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

## Minimal usage

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.

## Usage

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

export function Example() {
  return (
    <Spinner aria-label="Loading projects" className="size-6 text-primary" />
  )
}
```

## 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

- [Skeleton](https://wunderui.com/components/skeleton) for content with a known layout that loads, such as a table, a list or a card
- [Progress](https://wunderui.com/components/progress) for a task that reports how far it has come, such as an upload
- [Button](https://wunderui.com/components/button) for the wait after pressing a button, since its pending state draws the spinner for you

## Behavior

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

- `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

### When to use

- Use it for a short wait tied to an action: a status line that saves, a panel that refreshes. When content with a known layout loads, use a Skeleton.

### Do

- When the spinner stands alone, pass a specific aria-label such as Saving changes. The default Loading says nothing about what is happening.
- Beside a visible text, hide the spinner from screen readers and make the text a status, so the change is announced once, not twice.
- 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.
- 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 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 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

| Prop | Type | Default |
|---|---|---|


Also accepts React.SVGAttributes attributes.

## Examples

### Placement: beside text, in a panel, or over content

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

export function Example() {
  return (
    <p role="status" className="flex items-center gap-2 text-sm text-text-secondary">
      <Spinner aria-hidden />
      Syncing 3 files
    </p>
  )
}
```

### Name: on its own, or hidden beside a visible text

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

export function Example() {
  return (
    <Spinner aria-label="Saving changes" className="size-6 text-primary" />
  )
}
```

## In context

### Autosave: a spinner while it saves, a check when it is done

The status line has a fixed height, so the card does not move when the icon changes. Switch the status to see both.

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
import { Spinner } from "@/components/ui/spinner"

export function Example() {
  return (
    <Card className="w-96 max-w-full">
      <CardHeader>
        <CardTitle>Profile</CardTitle>
        <CardDescription>Your changes are saved automatically.</CardDescription>
      </CardHeader>
      <CardContent>
        <p role="status" className="flex h-5 items-center gap-2 text-sm text-text-secondary">
          <Spinner aria-hidden />
          Saving…
        </p>
      </CardContent>
    </Card>
  )
}
```

### Sync row: a spinner in place of the icon, and the action that stops the job

The spinner and the pause icon are the same 24 px, so the row keeps its layout when the job pauses.

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

export function Example() {
  return (
    <div className="flex w-96 max-w-full items-center gap-3 rounded-xl border border-border bg-card p-2 ps-3">
      <Spinner aria-hidden className="size-6 text-primary" />
      <div role="status" className="flex flex-1 flex-col text-sm">
        <p className="font-medium text-foreground">Syncing 3 files</p>
        <p className="text-text-secondary">About 20 seconds left</p>
      </div>
      <Button variant="plain" size="sm">
        Pause
      </Button>
    </div>
  )
}
```

### Loading panel: a large spinner and one line in an empty panel

Use it when a panel has no layout to show yet. If the layout is known, use a Skeleton instead.

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

export function Example() {
  return (
    <div className="flex h-48 w-80 max-w-full flex-col items-center justify-center gap-3 rounded-xl border border-border bg-card">
      <div role="status" className="flex flex-col items-center gap-3">
        <Spinner aria-hidden className="size-8 text-primary" />
        <p className="text-sm font-medium text-foreground">Loading dashboard…</p>
      </div>
      <p className="text-sm text-text-secondary">This takes a few seconds.</p>
    </div>
  )
}
```

## For AI agents

`get_component("spinner")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
