Spinner

View source on GitHub

See recent changes on GitHub

Spinner helps indicate that a surface's content or portion of content is currently loading.

also known as Refresh Indicator, Refresh Control, Loader, Circular Loader, Loading Animation

Figma:

Ready

Responsive:

Ready

Adaptive:

N/A

Props

Component props
Name	Type	Default
`show` Required	`boolean`	-
	Indicates if Spinner should be visible. Controlling the component with this prop ensures the outro animation is played. If outro aimation is not intended, prefer conditional rendering.
`accessibilityLabel`	`string`	-
	String that clients such as VoiceOver will read to describe the element. Always localize the label.
`color`	`"default" \| "subtle"`	`"subtle"`
	Color of the Spinner.
`delay`	`boolean`	`true`
	Whether or not to render with a 300ms delay. The delay is for perceived performance, so you should rarely need to remove it. See the delay variant for more details.
`size`	`"sm" \| "md"`	`"md"`
	sm: 32px, md: 40px

Usage guidelines

When to use

When loading or updating content on a surface.

When not to use

To communicate that a UI element, such as a button, is performing an action that takes a perceptible amount of time. Contact us if this is needed.

Best Practices

Only show Spinner if the expected wait time is perceptible — typically more than a second. Remember that wait times can vary based on the user's network connection.

Don't

Use Spinner if the wait time is likely longer than 10 seconds. Show incremental loading/completion progress instead.

Show Spinner where the content is being loaded or updated to create a clear association with where results will appear.

Don't

Show more than one Spinner at a time to avoid an overly-busy interface. Show a single Spinner over the collection of loading content instead.

Screen underlying content when overlaid by Spinner.

Don't

Display a loading label adjacent to Spinner when the label is redundant.

Accessibility

Be sure to include accessibilityLabel. Labels should relate to the specific part of the product where Spinner is being used (e.g. "Loading homefeed" when used on the homefeed surface). Don't forget to localize the label!

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

Note that accessibilityLabel is optional as DefaultLabelProvider provides default strings. Use custom labels if they need to be more specific.

Spinner depends on DefaultLabelProvider for internal text strings. Localize the texts via DefaultLabelProvider. Learn more

import { DefaultLabelProvider, Flex, Spinner, useReducedMotion } from 'gestalt';

export default function Example() {
  const reduced = useReducedMotion();
  return (
    <DefaultLabelProvider
      labels={{
        Spinner: {
          accessibilityLabel: 'Analysetabelle wird geladen.',
        },
      }}
    >
      <Flex
        alignItems="center"
        height="100%"
        justifyContent="center"
        width="100%"
      >
        <Spinner show={!reduced} />
      </Flex>
    </DefaultLabelProvider>
  );
}

Variants

Delay

By default, Spinner uses a 300ms delay to improve perceived performance. This can be disabled if needed.

import { Fragment, useState } from 'react';
import { Box, Button, Flex, Spinner } from 'gestalt';

export default function Example() {
  const [show, setShow] = useState(true);
  const [hasDelay, setHasDelay] = useState(true);

  return (
    <Fragment>
      <Box padding={2}>
        <Flex direction="column" gap={2}>
          <Button
            onClick={() => setShow((currVal) => !currVal)}
            size="md"
            text={show ? 'Hide spinner' : 'Show spinner'}
          />

          <Button
            onClick={() => setHasDelay((currVal) => !currVal)}
            size="md"
            text={hasDelay ? 'Disable delay' : 'Enable delay'}
          />
        </Flex>
      </Box>

      <Spinner
        accessibilityLabel="Example spinner"
        delay={hasDelay}
        show={show}
      />
    </Fragment>
  );
}

Component quality checklist

Component quality checklist
Quality item	Status	Status description
Figma Library	Ready	Component is available in Figma for web and mobile web.
Responsive Web	Ready	Component responds to changing viewport sizes in web and mobile web.

Edit page on GitHub