Spinner

A cross-platform React loading indicator with five sizes and theme-aware default colour.

Spinner is a circular animated indicator that shows an ongoing process when the wait time is unknown.

When to use

While loading content, submitting, or waiting for a response of indefinite length

Inline (in a button, field) or centered in a container that's loading

When not to use

• When progress is measurable — use a progress bar instead
• For very long or background tasks — use a clearer status message instead

Content guidelines

No text is built in; pair with a short "Loading…" message when context isn't obvious.

Pick the size (XL–XS) to match the area it sits in.

Behaviour guidelines

Spins continuously until the process finishes, then is removed and replaced by the result.

Stays centered in its space; don't shift surrounding layout when it appears or disappears.

Accessibility

Announce the loading state to assistive technology (e.g. a live region or "busy" state), not by the animation alone.

Respect reduced-motion preferences.

Ensure the spinner has enough contrast against its background.

Installation

npm install @xsolla/xui-spinner

Imports

import { Spinner, type SpinnerProps } from '@xsolla/xui-spinner';

Quick start

import * as React from 'react';
import { Spinner } from '@xsolla/xui-spinner';

export default function QuickStart() {
  return <Spinner />;
}

API Reference

<Spinner>

| Prop | Type | Default | Description | | --- | --- | --- | --- | | size | "xl" \| "lg" \| "md" \| "sm" \| "xs" | "md" | Spinner size. | | color | string | theme content.primary | Custom stroke colour. | | aria-label | string | "Loading" | Accessible label. | | aria-describedby | string | — | ID of an element describing what's loading. | | testID | string | — | Test identifier. |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

Sizes

| Size | Diameter | | --- | --- | | xs | 8px | | sm | 16px | | md | 24px | | lg | 48px | | xl | 96px |

Examples

Sizes

import * as React from 'react';
import { Spinner } from '@xsolla/xui-spinner';

export default function SpinnerSizes() {
  return (
    <div style={{ display: 'flex', gap: 24, alignItems: 'center' }}>
      <Spinner size="xs" />
      <Spinner size="sm" />
      <Spinner size="md" />
      <Spinner size="lg" />
      <Spinner size="xl" />
    </div>
  );
}

Custom colour

import * as React from 'react';
import { Spinner } from '@xsolla/xui-spinner';

export default function ColouredSpinners() {
  return (
    <div style={{ display: 'flex', gap: 24 }}>
      <Spinner color="#3498db" />
      <Spinner color="#e74c3c" />
      <Spinner color="#2ecc71" />
    </div>
  );
}

Inline with text

import * as React from 'react';
import { Spinner } from '@xsolla/xui-spinner';

export default function InlineLoading() {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
      <Spinner size="sm" />
      <span>Saving changes…</span>
    </div>
  );
}

Loading button state

import * as React from 'react';
import { Spinner } from '@xsolla/xui-spinner';
import { Button } from '@xsolla/xui-button';

export default function LoadingButton() {
  const [loading, setLoading] = React.useState(false);
  return (
    <Button onPress={() => { setLoading(true); setTimeout(() => setLoading(false), 1200); }} disabled={loading}>
      {loading ? <Spinner size="sm" color="white" /> : 'Submit'}
    </Button>
  );
}

Accessibility

• Renders with role="status" and aria-live="polite" so screen readers announce the loading state.
• Default aria-label is "Loading"; override for context-specific messages such as "Loading orders".
• Pair with aria-describedby when describing what the spinner relates to.