XDS — Design System

Spinner@xds/core · XDSSpinner v0.0.13

Usage

An animated loading indicator for processes with unknown duration, such as data fetching or form submission. Supports visible labels, multiple sizes, and a dark background variant. For content with known dimensions, use Skeleton instead.

ts
import {XDSSpinner} from '@xds/core/Spinner'

Best practices

Guidance	Practices
Do	Provide a meaningful label to describe what is loading for screen reader users.
Do	Use the "onMedia" shade when placed on dark or accent-colored backgrounds.
Don't	Use for content areas with known dimensions — use Skeleton to preserve layout instead.
Don't	Stack multiple spinners in the same view — use one to represent the overall loading state.

Examples

Common configurations, variations, and states.

Spinner — On Media ShadeDefault and onMedia shade spinners for light and dark backgrounds.

tsx
'use client';
import {XDSSpinner} from '@xds/core/Spinner';
import {XDSHStack} from '@xds/core/Layout';
export default function SpinnerOnMedia() {
  return (
    <XDSHStack gap={4} vAlign="center">
      <XDSSpinner shade="default" />
      <div
        style={{
          backgroundColor: '#1a1a2e',
          padding: 16,
          borderRadius: 8,
        }}>
        <XDSSpinner shade="onMedia" />
      </div>
    </XDSHStack>
  );
}

Spinner — SizesAll spinner sizes displayed side by side.

tsx
'use client';
import {XDSSpinner} from '@xds/core/Spinner';
import {XDSHStack} from '@xds/core/Layout';
export default function SpinnerSizes() {
  return (
    <XDSHStack gap={4} vAlign="center">
      <XDSSpinner size="sm" />
      <XDSSpinner size="md" />
      <XDSSpinner size="lg" />
      <XDSSpinner size="xl" />
    </XDSHStack>
  );
}

Spinner — With LabelSpinners with text and rich multi-line labels.

tsx
'use client';
import {XDSSpinner} from '@xds/core/Spinner';
import {XDSText} from '@xds/core/Text';
import {XDSHStack, XDSVStack} from '@xds/core/Layout';
export default function SpinnerWithLabel() {
  return (
    <XDSHStack gap={8} vAlign="start">
      <XDSSpinner size="lg" label="Loading..." />
      <XDSSpinner
        size="lg"
        label={
          <XDSVStack gap={0} hAlign="center">
            <XDSText type="body" weight="bold">
              Fetching data
            </XDSText>
            <XDSText type="supporting" color="secondary">
              This may take a moment
            </XDSText>
          </XDSVStack>
        }
        aria-label="Fetching data"
      />
    </XDSHStack>
  );
}

Showcase source

tsx
'use client';
import {XDSSpinner} from '@xds/core/Spinner';
export default function SpinnerShowcase() {
  return <XDSSpinner size="lg" />;
}

Usage

import {XDSSpinner} from '@xds/core/Spinner'

Best practices

Guidance	Practices
Do	Provide a meaningful label to describe what is loading for screen reader users.
Do	Use the "onMedia" shade when placed on dark or accent-colored backgrounds.
Don't	Use for content areas with known dimensions — use Skeleton to preserve layout instead.
Don't	Stack multiple spinners in the same view — use one to represent the overall loading state.

tsx

'use client'; import {XDSSpinner} from '@xds/core/Spinner'; import {XDSHStack} from '@xds/core/Layout'; export default function SpinnerOnMedia() { return ( <XDSHStack gap={4} vAlign="center"> <XDSSpinner shade="default" /> <div style={{ backgroundColor: '#1a1a2e', padding: 16, borderRadius: 8, }}> <XDSSpinner shade="onMedia" /> </div> </XDSHStack> ); }

tsx

'use client'; import {XDSSpinner} from '@xds/core/Spinner'; import {XDSHStack} from '@xds/core/Layout'; export default function SpinnerSizes() { return ( <XDSHStack gap={4} vAlign="center"> <XDSSpinner size="sm" /> <XDSSpinner size="md" /> <XDSSpinner size="lg" /> <XDSSpinner size="xl" /> </XDSHStack> ); }

tsx

'use client'; import {XDSSpinner} from '@xds/core/Spinner'; import {XDSText} from '@xds/core/Text'; import {XDSHStack, XDSVStack} from '@xds/core/Layout'; export default function SpinnerWithLabel() { return ( <XDSHStack gap={8} vAlign="start"> <XDSSpinner size="lg" label="Loading..." /> <XDSSpinner size="lg" label={ <XDSVStack gap={0} hAlign="center"> <XDSText type="body" weight="bold"> Fetching data </XDSText> <XDSText type="supporting" color="secondary"> This may take a moment </XDSText> </XDSVStack> } aria-label="Fetching data" /> </XDSHStack> ); }