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:

Responsive:

Adaptive:

A11y:

Props

Component props
Name
Type
Default
show
Required
boolean
-

Indicates if Spinner should be visible.

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

Do

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.

Do

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.

Do

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
      // $FlowExpectedError[incompatible-type] For demostration purposes
      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.