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
Emptywhen the region loaded and has no data, no results, or no access to show. - Prefer
ProgressBarwhen 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
Emptyinstead. - 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.