Spinner

A visual indicator that a process is happening in the background but the interface is not yet ready for interaction.

styleKeys: spinner

Some props/prop values deprecated in SWAN v3.3
Refer to the information on props/prop values provided further down this page. Find more information and migration documentation in the Deprecation roadmap.

UsageGuidelinesAPI

Use Spinner...

To provide feedback for user interaction.
When loading time is expected to take between 1 and 10 seconds.

Don't use Spinner...

To show loading progress or time remaining. Use Progress Bar instead.
When loading time is expected to take longer than 10 seconds. Use Progress Bar instead.
To indicate an image is loading. Use the Loading Shimmer background color instead.

<Spinner accessibleText="Loading..." />

<Spinner accessibleText="Loading..." />

Size

Standard

Use size="standard" for most use cases.

<Spinner accessibleText="Loading..." />

<Spinner accessibleText="Loading..." />

Super

Use size="super" for larger elements, such as a full page load.

<Spinner size="super" accessibleText="Loading..." />

<Spinner size="super" accessibleText="Loading..." />

Mini

skin="mini" is deprecated in SWAN v3.3
Use the skin="standard" instead, which aligns with new semantic roles on SWAN components.

Use size="mini" for smaller individual UI elements, such as an Alert Box.

<Spinner size="mini" accessibleText="Loading..." />

<Spinner size="mini" accessibleText="Loading..." />

Tiny

skin="tiny" is deprecated in SWAN v3.3
Use the skin="standard" instead, which aligns with new semantic roles on SWAN components.

Use size="tiny" for smaller individual UI elements, such as a Button (refer to Inside a Button below).

<Spinner size="tiny" accessibleText="Loading..." />

<Spinner size="tiny" accessibleText="Loading..." />

Text label

All Spinners must have accessible text, which is ordinarily hidden on screens. Use accessibleText to describe the function of the Spinner. Use showText to make that text visible for everyone.

Use showText if loading time is expected to take longer than 2 seconds.

<Spinner accessibleText="Loading..." showText />

<Spinner accessibleText="Loading..." showText />

Layout

Visible text is displayed below the Spinner. Use layout="horizontal" to display visible text to the right of the Spinner.

<GridContainer>
  <Row>
    <Column span={6}>
      <Spinner accessibleText="Loading..." showText />
    </Column>
    <Column span={6}>
      <Spinner accessibleText="Loading..." layout="horizontal" showText />
    </Column>
  </Row>
</GridContainer>

<GridContainer>
  <Row>
    <Column span={6}>
      <Spinner accessibleText="Loading..." showText />
    </Column>
    <Column span={6}>
      <Spinner accessibleText="Loading..." layout="horizontal" showText />
    </Column>
  </Row>
</GridContainer>

Overlay

Use overlay="true" to show a white box behind the Spinner, which can help make it more visible when displaying over other content (eg. to indicate that the full page is loading).

<GridContainer>
  <Row>
    <Column span={4}>
      <Spinner accessibleText="Loading..." overlay showText />
    </Column>
    <Column span={4}>
      <Spinner
        accessibleText="Loading..."
        overlay
        showText
        layout="horizontal"
      />
    </Column>
    <Column span={4}>
      <Spinner accessibleText="Loading..." overlay />
    </Column>
  </Row>
</GridContainer>

<GridContainer>
  <Row>
    <Column span={4}>
      <Spinner accessibleText="Loading..." overlay showText />
    </Column>
    <Column span={4}>
      <Spinner
        accessibleText="Loading..."
        overlay
        showText
        layout="horizontal"
      />
    </Column>
    <Column span={4}>
      <Spinner accessibleText="Loading..." overlay />
    </Column>
  </Row>
</GridContainer>

Inside a Button

A Spinner can be placed inside a disabled Button to show that an action is still in progress. Use a size="tiny" Spinner for this.

<Button disabled>
  <Spinner size="tiny" accessibleText="Submitting..." />
  Submitting
</Button>

<Button disabled>
  <Spinner size="tiny" accessibleText="Submitting..." />
  Submitting
</Button>

Accessibility

Spinners need ARIA attributes for a11y support. The component does not provide these automatically, since the right attributes can depend on context.

Spinners need a role attribute. Typically this will be role="alert" when the Spinner functions as a form of alert. However, this might also be a value of status if the Spinner contains status information.
Spinners should have an aria-live attribute. Typically this should be aria-live="polite". If the Spinner is particularly critical and should be announced immediately (e.g. a full-page overlay with a Spinner on it), consider aria-live="assertive" instead.
If a page container is getting new content while the Spinner is shown, remember to put aria-busy="true" on that container while the loading is happening, and set it to false when done.

Best practices

If disabling a part of an interface during loading (e.g. loading a form), center the spinner and provide a semi-transparent black scrim.
Only show one spinner on screen at a time.
When only a portion of a page is being updated, place the Spinner in that part of the page.

Content

Use showText if loading time is expected to take longer than 2 seconds.
The text can explain:
- What the system is doing.
- What the user will soon see or experience.
Include an ellipsis after the text to communicate that the system is loading.
Use gerunds (like Saving, Loading, etc.) to indicate that the action is currently in progress.
Keep the text to one line wherever possible.

Props

Spinner

This component is implemented using the <span /> as the root element. You can utilize the native attributes supported by <span /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

prop	type	required	description	default
accessibleText	`string`	true	A localized string which will be used for shown beside the spinner as well as for accessibility to read aloud by screen-readers	null
size	`"standard" \| "super" \| "mini" \| "tiny" \| null`	false	The visual style of the Loader	standard Size "mini" and "tiny" are deprecated. Use "standard" instead
overlay	`boolean \| null`	false	Using this will create a box behind the spinner	false
layout	`"horizontal" \| "vertical" \| null`	false	The alignment of text beside the spinner	vertical
showText	`boolean \| null`	false	Hide or show the accessibleText	false