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 animation 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" \| "grayscale" \| "white"`	`"subtle"`
	Color of the Spinner. `grayscale` and `white` variants are available only in Visual Refresh experiment.
`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.
`label`	`string`	-
	Adds a label under the spinning animation.
`size`	`"sm" \| "md" \| "lg"`	`"md"`
	sm: 32px, md: 40px, lg: 56px. 'lg' is available only in Visual Refresh experiment and is the default value.

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

accessibilityLabel should relate to the specific part of the product where Spinner is being used (e.g. "Loading homefeed" when used on the homefeed surface).

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

If label is provided, accessibilityLabel is not needed. accessibilityLabel overrides label for assistive technologies. Therefore, avoid overriding label if accessibilityLabel is less specific.

The override order for labels: accessibilityLabel overrides label, label overrides default label from DefaultLabelProvider. DefaultLabelProvider is only accessible if there is not accessibilityLabel not 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. DefaultLabelProvider is override by label.

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

Colors

By default, Spinner has color-change animation. Non-default color variant are grayscale and white.

Grayscale

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

export default function Example() {
  const reduced = useReducedMotion();
  return (
    <Box height="100%" width="100%">
      <Flex
        alignItems="center"
        height="100%"
        justifyContent="center"
        width="100%"
      >
        <Spinner color="grayscale" show={!reduced} />
      </Flex>
    </Box>
  );
}

White

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

export default function Example() {
  const reduced = useReducedMotion();
  return (
    <Box color="inverse" height="100%" width="100%">
      <Flex
        alignItems="center"
        height="100%"
        justifyContent="center"
        width="100%"
      >
        <Spinner color="white" show={!reduced} />
      </Flex>
    </Box>
  );
}

Label

Spinner supports a label. See the Accessibility guidelines for more information

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

export default function Example() {
  const reduced = useReducedMotion();
  return (
    <Box height="100%" width="100%">
      <Flex
        alignItems="center"
        height="100%"
        justifyContent="center"
        width="100%"
      >
        <Spinner
          accessibilityLabel="test"
          label="We’re adding new ideas to your homefeed"
          show={!reduced}
        />
      </Flex>
    </Box>
  );
}

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