> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# Spinner

Feedback`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Indicates indeterminate loading activity.

## When to use

Use Spinner for short indeterminate waits when progress cannot be measured.

**Recommended**

- Prefer inline placement near the content that is loading.
- Use aria labels for standalone spinners.

**Avoid**

- Do not use Spinner for determinate progress.

## Examples


### Basic usage
```tsx preview
import { Spinner, Stack } from '@rockshin/tao-ui';

function SpinnerExample() {
  return (
    <Stack direction="horizontal" gap="lg" align="center">
      <Spinner size="small" />
      <Spinner size="medium" tip="Loading" />
      <Spinner size="large" />
    </Stack>
  );
}

export default SpinnerExample;
```

### Tips and custom indicators
```tsx preview
import { Spinner, Stack } from '@rockshin/tao-ui';

function SpinnerIndicators() {
  return (
    <Stack direction="horizontal" gap="lg" align="center">
      <Spinner tip="Loading data" />
      <Spinner
        indicator={<span style={{ fontSize: 24 }}>◌</span>}
        tip="Custom"
      />
      <Spinner size="large" tip="Preparing preview" />
    </Stack>
  );
}

export default SpinnerIndicators;
```

### Content overlay and delay
```tsx preview
import { Button, Spinner, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';

function SpinnerOverlay() {
  const [spinning, setSpinning] = useState(true);

  return (
    <Stack gap="md" style={{ maxWidth: 420 }}>
      <Button
        variant="secondary"
        onClick={() => setSpinning((value) => !value)}
      >
        {spinning ? 'Stop' : 'Start'} loading
      </Button>
      <Spinner spinning={spinning} delay={200} tip="Loading content">
        <div
          style={{
            minHeight: 120,
            padding: 20,
            border: '1px solid var(--tao-color-border)',
          }}
        >
          Content remains mounted below the overlay.
        </div>
      </Spinner>
    </Stack>
  );
}

export default SpinnerOverlay;
```

### Loading over content
spinning controls loading over a content area.
```tsx preview
import { Spinner, Stack } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function SpinnerWrapContent() {
  function Demo() {
    const [spinning, setSpinning] = useState(true);
    return (
      <Stack gap="md" style={{ maxWidth: 360 }}>
        <button type="button" onClick={() => setSpinning((s) => !s)}>
          {spinning ? 'Stop' : 'Start'} loading
        </button>
        <Spinner spinning={spinning} tip="Loading">
          <div
            style={{
              padding: 24,
              border: '1px solid var(--tao-color-border)',
              borderRadius: 8,
              lineHeight: 1.6,
            }}
          >
            <h4 style={{ margin: '0 0 8px' }}>Card title</h4>
            <p style={{ margin: 0 }}>
              Content stays in place and dims while the spinner overlays it.
            </p>
          </div>
        </Spinner>
      </Stack>
    );
  }
  return <Demo />;
}
```

### Delayed loading
A short request can finish before delay to avoid flicker.
```tsx preview
import { Spinner, Stack } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function SpinnerDelay() {
  function Demo() {
    const [spinning, setSpinning] = useState(false);
    return (
      <Stack gap="md" style={{ maxWidth: 360 }}>
        <p style={{ color: 'var(--tao-color-text-secondary)', fontSize: 13 }}>
          500ms delay — quick toggles won&apos;t flash the spinner.
        </p>
        <button type="button" onClick={() => setSpinning((s) => !s)}>
          Toggle spinning ({String(spinning)})
        </button>
        <Spinner spinning={spinning} delay={500}>
          <div
            style={{
              padding: 24,
              border: '1px solid var(--tao-color-border)',
              borderRadius: 8,
            }}
          >
            Toggle quickly to see the delay in action.
          </div>
        </Spinner>
      </Stack>
    );
  }
  return <Demo />;
}
```

### Custom indicator
indicator replaces the visual mark; retain clear status text.
```tsx preview
import { Spinner } from '@rockshin/tao-ui';

export default function SpinnerCustomIndicator() {
  return (
    <Spinner
      indicator={<span style={{ fontSize: 24 }}>⏳</span>}
      tip="Please wait"
    />
  );
}
```

### Controlled loading
Control spinning externally while keeping content in place.
```tsx preview
import { useState } from 'react';
import { Spinner, Switch, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [loading, setLoading] = useState(false);
  return (
    <Stack direction="vertical">
      <Switch
        aria-label="Loading"
        checked={loading}
        onChange={setLoading}
        style={{ alignSelf: 'flex-start' }}
      />
      <Spinner spinning={loading} tip="Loading content">
        <div style={{ padding: 24 }}>Your workspace content stays here.</div>
      </Spinner>
    </Stack>
  );
}
```

## API


### [#](#spinner)Spinner



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| spinning | Whether the spinner is visible. Defaults to true. | `boolean | undefined` | `true` |
| size | Size of the indicator. Inherits from TaoProvider. | `TaoSize | undefined` | `-` |
| tip | Description text rendered under the indicator. | `ReactNode` | `-` |
| delay | Delay (ms) before showing the spinner — prevents flicker on fast loads. | `number | undefined` | `-` |
| indicator | Custom indicator node, replaces the default spinner. | `ReactNode` | `-` |
| children | Wrap content: the spinner overlays `children` while spinning. | `ReactNode` | `-` |
| fullscreen | Render a full-screen backdrop with a centered spinner. | `boolean | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |

