Spinner

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

Web:

iOS:

Android:

A11y:

Props

Component props
Name	Type	Default
`accessibilityLabel` Required	`string`	-
	String that clients such as VoiceOver will read to describe the element. Always localize the label.
`show` Required	`boolean`	-
	Indicates if Spinner should be visible.
`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

Ready

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 accessibilityLabel. Be mindful of label length so that it isn't truncated in languages with lengthier character counts.

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
            text={show ? 'Hide spinner' : 'Show spinner'}
            onClick={() => setShow((currVal) => !currVal)}
            size="md"
          />

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

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

Component quality checklist

Component quality checklist
Quality item	Status	Status description
Figma Library	Ready	Component is available in Figma across all platforms.
Responsive Web	Ready	Component is available in code for web and mobile web.
iOS		Component is not currently available in code for iOS.
Android		Component is not currently available in code for Android.

Edit page on GitHub

; Opens a new tab