# Spinner

> Spinner indicates that something is in progress. The ring is sized in em, so it scales with the size prop and lines up with text.

Source: https://vaneui.com/docs/basic-components/spinner

Import: `import { Spinner, Badge, Card, Col, Row, Text } from "@vaneui/ui"`

Spinner stands in for content that is not there yet, while data loads or a job runs. It renders an inline-block `<span>` and takes no padding, border or shape props. For a button waiting on its own action, set `loading` on [Button](/docs/basic-components/button) instead of placing a Spinner inside it by hand. For a full-screen loading state, place the Spinner on an [Overlay](/docs/overlay-components/overlay).

## Basic usage

Spinner indicates that something is in progress. Give it an `aria-label` so the busy state has a name, since the ring itself carries no text.

```tsx demo
<Spinner aria-label="Loading"/>
```

It renders `role="status"`, so assistive technology announces the label when the spinner appears.

## Sizes

The ring is one em square, so it scales with the size prop and lines up with text of the same size.

```tsx demo
<Row itemsCenter flexWrap>
  <Spinner xs aria-label="Loading"/>
  <Spinner sm aria-label="Loading"/>
  <Spinner aria-label="Loading"/>
  <Spinner lg aria-label="Loading"/>
  <Spinner xl aria-label="Loading"/>
</Row>
```

## Appearances

The ring is drawn in the current text colour, so an appearance prop colours it directly.

```tsx demo
<Row itemsCenter flexWrap>
  <Spinner primary aria-label="Loading"/>
  <Spinner accent aria-label="Loading"/>
  <Spinner secondary aria-label="Loading"/>
  <Spinner tertiary aria-label="Loading"/>
  <Spinner success aria-label="Loading"/>
  <Spinner danger aria-label="Loading"/>
  <Spinner warning aria-label="Loading"/>
  <Spinner info aria-label="Loading"/>
</Row>
```

## Variants

An appearance only becomes a colour through a variant, so Spinner carries the same `outline` / `filled` / `ghost` axis as everything else. It has no background of its own, so the variant does one thing here: it picks which colour of the appearance the ring paints in.

`outline`, the default, uses the appearance's own colour, for a spinner on a plain surface. `filled` uses the "on this fill" colour, for a spinner sitting on a filled surface of the same appearance.

```tsx demo
<Col>
  <Row itemsCenter flexWrap>
    <Spinner danger aria-label="Loading"/>
    <Spinner success aria-label="Loading"/>
    <Spinner info aria-label="Loading"/>
  </Row>
  <Row flexWrap>
    <Card danger filled wFit><Spinner danger filled aria-label="Loading"/></Card>
    <Card success filled wFit><Spinner success filled aria-label="Loading"/></Card>
    <Card info filled wFit><Spinner info filled aria-label="Loading"/></Card>
  </Row>
</Col>
```

Most of the time you do not need either. With no appearance prop the Spinner inherits the colour of whatever it sits in, which is what makes it readable inside a filled Badge, Card or Button without being told anything.

```tsx demo
<Row itemsCenter flexWrap>
  <Badge info filled><Spinner xs aria-label="Loading"/> Syncing</Badge>
  <Card sm filled secondary wFit>
    <Row itemsCenter>
      <Spinner sm aria-label="Loading"/>
      <Text sm>Rebuilding index</Text>
    </Row>
  </Card>
</Row>
```

Setting an appearance that matches the surface you are on is the one thing to avoid: `<Spinner secondary>` inside a `secondary filled` Card resolves to the outline colour, which is the surface's own colour, so the ring disappears.

`Button` and `IconButton` render this same component for their `loading` prop, so there is one spinner in the library and restyling `theme.spinner` restyles both. That state is documented where it is used, on [Button](/docs/basic-components/button) and [IconButton](/docs/basic-components/icon-button).

Spinner honours `prefers-reduced-motion`: the animation stops for users who ask for less motion.

## Inline with text

Because the ring is sized in em, it matches the surrounding text without any manual tuning.

```tsx demo
<Row itemsCenter>
  <Spinner sm aria-label="Loading"/>
  <Text sm secondary>Checking availability…</Text>
</Row>
```

## Props

| Prop | Category | Default | Description |
| --- | --- | --- | --- |
| `primary` | Appearance |  | Primary color appearance (gray) |
| `accent` | Appearance |  | Accent color appearance (rose) |
| `secondary` | Appearance |  | Secondary color appearance (gray) |
| `tertiary` | Appearance |  | Tertiary color appearance |
| `success` | Appearance |  | Success color appearance (green) |
| `danger` | Appearance |  | Danger color appearance (red) |
| `warning` | Appearance |  | Warning color appearance (amber) |
| `info` | Appearance |  | Info color appearance (cyan) |
| `inheritAppearance` | Appearance | yes | Inherit appearance from parent — suppresses own data-appearance/data-variant, uses parent's CSS variables |
| `margin` | Margin |  | Enable margin on all sides |
| `marginX` | Margin |  | Enable only horizontal (inline) margin |
| `marginY` | Margin |  | Enable only vertical (block) margin |
| `marginT` | Margin |  | Enable only top margin |
| `marginB` | Margin |  | Enable only bottom margin |
| `noMargin` | Margin | yes | Disable margin (reset to 0) |
| `xs` | Size |  | Extra small size |
| `sm` | Size |  | Small size |
| `md` | Size | yes | Medium size (default) |
| `lg` | Size |  | Large size |
| `xl` | Size |  | Extra large size |
| `filled` | Variant |  | Filled variant - solid background with contrasting text color |
| `outline` | Variant | yes | Outline variant - transparent background with border and colored text (default) |
| `ghost` | Variant |  | Ghost variant - transparent background, no border, appearance-colored text, tinted hover background |

Layout and utility props (Display, Hide, Show) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).
