# Spinner

Shows that something is loading.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Spinner.tsx)

Figma: [Spinner](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1186-3872)

## Overview

An indeterminate loading indicator whose arc draws in the current text color, optionally on an elevated tile. Pass `aria-label` to name what loads.

## Examples

### Basic

```tsx
import { Spinner } from '@tempoxyz/ds'

export function Demo() {
  return <Spinner aria-label="Loading transactions" />
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Spinner/Basic.tsx)

### Elevated

Set `elevated` to place the spinner on a 44px raised tile with a shadow.

```tsx
import { Spinner } from '@tempoxyz/ds'

export function Demo() {
  return <Spinner aria-label="Loading quote" elevated />
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Spinner/Elevated.tsx)

### Size

Set `size="40"` for a 40px ring with a thicker stroke, such as a spinner that fills an empty panel.

```tsx
/** Renders the 16px and 40px spinner rings side by side. @module */
import { Spinner } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div style={{ alignItems: 'center', display: 'flex', gap: 24 }}>
      <Spinner aria-label="Loading balance" />
      <Spinner aria-label="Loading activity" size="40" />
    </div>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Spinner/Size.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Spinner } from '@tempoxyz/ds'

<Spinner />
```

## Guidelines

### When to Use

* Mark a region busy for a short, unknown time, such as a table that refreshes after a filter change.
* Mark a small area that fetches data, such as a quote card or an address lookup.
* Hold the place of a result with no predictable shape, such as a quote that returns a price or an error.

### When Not to Use

* Use `loading` on a [Button](/docs/components/button) while its action runs, not a spinner beside it.
* Use [Skeleton](/docs/components/skeleton) for content with a known shape, such as activity rows or metric tiles.
* Use [Progress](/docs/components/progress) for measurable work, or any wait over about 10 seconds.
* Use [LoadingDots](/docs/components/loading-dots) for a short wait inside a line of text.

### Match the Indicator to the Wait

* **Under About 300 ms (nothing):** Show nothing. Render the result when it arrives.
* **About 300 ms to 10 Seconds (Spinner):** Mark the busy region or control.
* **Over About 10 Seconds (Progress):** Show a value for measurable work.

Once a spinner appears, keep it for at least about 500 ms so it doesn't flash. For whole pages, see [Loading](/docs/patterns/loading).

### Use One Spinner per Region

**Do:** Center one spinner where the content will appear, and keep loaded content visible.

```tsx
/**
 * Do example for "Use One Spinner per Region" on the Spinner page.
 * Center one spinner where the content will appear, and keep loaded content visible.
 * @module
 */
import { Spinner, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <Surface size="small" {...styles.card()}>
        <div {...styles.label()}>Balance</div>
        <div {...styles.value()}>1,250.00 USDC</div>
      </Surface>
      <Surface size="small" {...styles.region()}>
        <Spinner aria-label="Loading activity" />
      </Surface>
    </div>
  )
}

namespace styles {
  export const card = style({ display: 'flex', flexDirection: 'column', gap: '4' })

  export const label = style({ color: 'content.secondary', typography: 'body.b3' })

  export const page = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '12',
    width: '100% !custom',
  })

  export const region = style({
    alignItems: 'center',
    display: 'flex',
    height: '6rem !custom',
    justifyContent: 'center',
  })

  export const value = style({ color: 'content.primary', typography: 'heading.h2' })
}
```

**Don't:** Cover the whole page, which blocks content that already loaded.

```tsx
/**
 * Don't example for "Use One Spinner per Region" on the Spinner page.
 * Don't cover the whole page, which blocks content that already loaded.
 * @module
 */
import { Spinner, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Surface size="small" {...styles.page()}>
      <Spinner aria-label="Loading" />
    </Surface>
  )
}

namespace styles {
  export const page = style({
    alignItems: 'center',
    boxSizing: 'border-box',
    display: 'flex',
    height: '10rem !custom',
    justifyContent: 'center',
    width: '100% !custom',
  })
}
```

### Place It Beside a Status Line

Show the spinner inline beside a short status line, such as Approving. For a pending action, use `loading` on a [Button](/docs/components/button).

## Accessibility

A spinner renders an indeterminate `progressbar` named "Loading". It is not a live region, so it is read only when the reader reaches it.

### Semantics

* **Root (progressbar):** Named "Loading", with no value, so it reads as indeterminate.
* **Custom Name (aria-label):** Replaces the default name.
* **Ring (aria-hidden):** A hidden SVG that stops rotating under reduced motion.
* **Color (3:1):** Uses the text color. Keep 3:1 contrast against the background.

### Your Responsibilities

* **Say What Is Loading (aria-label):** Name what loads, such as "Loading transactions". Several spinners named "Loading" are indistinguishable.
* **Announce the Result (SC 4.1.3):** A spinner isn't announced. Announce the result or an error in a status message or a [Toast](/docs/components/toast).
* **Mark the Region Busy (aria-busy):** Set `aria-busy` on the loading region, so assistive technology waits for its content.

## Related

[Skeleton](/docs/components/skeleton)

Use for content with a known shape.

[Progress](/docs/components/progress)

Use for measurable work.

[LoadingDots](/docs/components/loading-dots)

Use for a wait inside a line of text.

[Button](/docs/components/button)

Use for an action's loading state.

[Loading](/docs/patterns/loading)

Covers choosing a loading indicator.
