XDS — Design System

XDSSpinner@xds/core · Spinner

Preview coming soon

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.

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.

Import

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

Props

Prop	Type	Description
size	'sm' \| 'md' \| 'lg' (default: 'md')	Spinner size (10px, 14px, 18px).
shade	'default' \| 'onMedia' (default: 'default')	Color shade for light or dark backgrounds.
label	ReactNode	Visible content below the spinner. String labels auto-set aria-label.
aria-label	string (default: 'Loading')	Accessible name for screen readers. Defaults to label (if string) or "Loading".
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

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" />;
}