Design System
v4.11.0
⌘K

Spinner

Mobile Support: Full
Jump to Props

Provide a visual cue that an action is processing or awaiting an update.

On this page

Import

import { Spinner } from "@vitality-ds/components";

Usage

<Spinner />
Aim For
  • Place the spinner in the part of the page or section that is updating.
  • If you are unsure where to place the spinner, place it where you want the user's attention to be when loading is finished.
Avoid
  • Try not to block the entire page with a Spinner unless absolutely necessary
  • Only show a spinner if the expected wait time is more than one second.

Sizes

When choosing sizes, consider the visual context in which the Spinner will be used. If it will appear inline with text or form elements, select a size that will cause minimal layout shift. When used to "block" a section of the UI, choose an appropriate size that provides enough visual breathing room around the spinner. Often that means one size smaller than you might have originally thought.

Common use cases for sizes

  • xs: Use inside toggles
  • sm: Use within elements such as buttons or form fields, or when there are other space constraints.
  • md: The default size which is used for most use cases
  • lg: Typically used in loading states of components with large space
  • xl: Typically used in fullscreen loading states
<Stack direction="horizontal" align="end" spacing="xl">
  <Stack align="center">
    <Spinner size="xs" />
    <Badge content="xs" />
  </Stack>
  <Stack align="center">
    <Spinner size="sm" />
    <Badge content="sm" />
  </Stack>
  <Stack align="center">
    <Spinner size="md" />
    <Badge content="md (default)" />
  </Stack>
  <Stack align="center">
    <Spinner size="lg" />
    <Badge content="lg" />
  </Stack>
  <Stack align="center">
    <Spinner size="xl" />
    <Badge content="xl" />
  </Stack>
</Stack>

Usage on "solid" background colors

Most of the time, the Spinner component will be on the base app background, so the default colour would be fine. There are some times however that you may need to place it on a "solid" background like the below examples.

To set the color, pass the onBackgroundColor prop to indicate which of the core severity colours are being used. Each spinner color will map to the onSolidBackgrounds use case for the severity color.

() => {
  const colors = [
    "neutral",
    "info",
    "success",
    "critical",
    "primary",
    "warning",
  ];

  const boxProps = { padding: "$xl" };

  return (
    <DocsBox
      css={{
        display: "grid",
        gap: "$xs",
        gridTemplateColumns: "repeat(4, 1fr)",
      }}
    >
      <DocsBox css={boxProps}>
        <Spinner />
      </DocsBox>
      {colors.map((color) => (
        <DocsBox css={{ ...boxProps, backgroundColor: `$${color}9` }}>
          <Spinner onBackgroundColor={color} />
        </DocsBox>
      ))}
    </DocsBox>
  );
};

Delay

For operations such as asynchronous data fetching, you may wish to prevent the spinner from displaying for a period of time. Pass the delay prop (in milliseconds) to provide a delay.

Try it out by changing the delay value below:

<Spinner delay={1000} />

© 2025