Skip to main content
On this page

Skeleton Loading

Skeleton loaders show the shape of content while it loads, reducing perceived wait time and preventing layout shift.

When to use​

  • When content takes more than around 300ms to load and the final layout is known in advance
  • When the page or section loads all its content at roughly the same time
  • To prevent layout shift: show skeleton shapes that match the size and position of the real content
  • To reduce perceived wait time by giving users a preview of what is coming

When not to use​

  • For operations under 300ms - a skeleton that flashes in and out creates more disruption than showing nothing. Use no indicator at all for very fast operations.
  • When the final layout is unknown - if you cannot accurately match the real content shape, a spinner is less disorienting. Use the Notification component to surface status messages when a background operation completes instead.
  • For the full page on every visit - once a user has seen the page layout, subsequent loads may not need skeletons. Cache what you can and show real content as soon as it is available.
  • When content is static - do not skeleton-load content that never changes. Show it immediately.

Anatomy​

  1. Skeleton shape (a block with the background colour colors.borderMuted)
  2. Gleam (an animated highlight that sweeps left to right across the shape, pausing on prefers-reduced-motion)

Basic usage​

Loading...
Edit live code
<Card>
  <SkeletonHeading />
  <SkeletonText lines={3} />
  <SkeletonCircle />
  <SkeletonCTA />
</Card>

Variants and features​

SkeletonText​

Use to represent one or more lines of body text. The last line renders at 50% width to mimic the natural end of a paragraph.

Loading...
Edit live code
<SkeletonText lines={3} />

SkeletonHeading​

Use to represent a heading. Defaults to Heading3 at 70% width. Pass headingComponent to match the real heading level, and size to match the real heading width.

Loading...
Edit live code
<>
  <SkeletonHeading />
  <SkeletonHeading headingComponent={Heading2} size="90%" />
</>

SkeletonCTA​

Use to represent a button or call-to-action area. Defaults to 25rem wide and space[12] (48px) tall.

Loading...
Edit live code
<SkeletonCTA size="20rem" />

SkeletonCircle​

Use to represent a circular element such as an avatar or icon container. Defaults to 12rem.

Loading...
Edit live code
<SkeletonCircle size="20rem" />

Custom shapes with Skeleton​

Skeleton is the base styled component. Use it directly to represent content shapes that none of the named variants cover. Set background-color and dimensions to match your content.

Loading...
Edit live code
<Skeleton style={{width: 200, height: 40}} />

Reduced motion​

The gleam animation is automatically disabled when the user has prefers-reduced-motion set. No additional configuration is needed.

Composing a skeleton screen​

Build a skeleton screen by composing the variants in the same layout as the real content. Use the same layout components (Stack, Cluster, etc.) that the real view uses so that content snaps into place without shifting.

Loading...
Edit live code
<Card>
  <Stack spaceBetween={4}>
    <SkeletonHeading headingComponent={Heading2} size="60%" />
    <SkeletonText lines={3} />
    <Cluster spaceBetween={2}>
      <ClusterItem>
        <SkeletonCTA size="14rem" />
      </ClusterItem>
      <ClusterItem>
        <SkeletonCTA size="14rem" />
      </ClusterItem>
    </Cluster>
  </Stack>
</Card>