Skip to main content

Skeleton

Use Skeleton to show a placeholder while content is loading.

When to use

  • Hold the place of async content whose shape you can predict: lists, cards, tables, avatars.
  • Fill the page on its first load, before the data resolves.
  • Show a whole list page while it loads. The List Page Loading States recipe shows where the skeleton belongs and what renders around it.
  • Prefer Empty when the region loaded and has no data, no results, or no access to show.
  • Prefer ProgressBar when a task shows how much of it is complete.

When not to use

  • For very short fetches (under ~200 ms). A flash of skeleton is more distracting than helpful.
  • To convey error or empty states. Use Empty instead.
  • As a permanent decorative shape.

Sizing

A skeleton renders a neutral block where the real content will appear. It gives the user an early sense of the layout, and it reduces both perceived loading time and Cumulative Layout Shift (CLS).

Default height is 1rem. Override className with h-*, w-*, and rounded-* utilities to match the real content's dimensions. The more closely the skeleton matches, the less layout shift on swap.

Accessibility

Skeletons are decorative and convey no semantic meaning to assistive tech, so Skeleton renders aria-hidden="true" by default. Pass aria-hidden={false} to opt out. If the underlying region is loading, also announce it to screen readers, for example wrap it in an element with role="status" and a visually-hidden "Loading…" label.

Examples

Composition: Skeleton within a Media Object

Include the Skeleton within other components. Pass Tailwind utility classes for further control.

Polymorphism

Skeleton accepts an asChild prop. When true, it renders its single child instead of its default <div>, forwarding its class names, data-* attributes, and ref onto that child. Reach for this when the placeholder should also be a more semantic element.

API Reference

Skeleton

The Skeleton accepts the following props in addition to the standard HTML div attributes.

PropTypeDefaultDescription
asChild?booleanfalseUse the asChild prop to compose the Skeleton styling and functionality onto alternative element types or your own React components.