Skeleton

Usage

Overview

Skeleton UI reserves space for content that is still loading, using neutral shapes that echo the final layout. It improves perceived performance and prevents layout jump when data arrives. The mental model is "structure is here; details are coming"—not "an error occurred". Reach for a skeleton when the shape of the loaded state is known; use a LoadingIndicator or a Progress bar when it isn't.

When to use

Initial page or card load where structure is known but values are not.
Lists and tables where row height is predictable.
Any fetch that commonly exceeds a few hundred milliseconds and would otherwise show blank space.

When not to use

Very fast loads where the skeleton flashes—prefer no placeholder or a delay threshold.
Unknown layout. A neutral LoadingIndicator is clearer.
Background refresh where existing content stays valid—update in place rather than skeletonizing the whole view.
Indeterminate long processes with no layout—use Progress plus messaging.

Behavior and states

Show. After a short threshold if the request is still pending. Avoid sub-200 ms flashes.
Hide. Immediately when content is ready. A subtle cross-fade is acceptable.
Error. Replace the skeleton region with an error Banner or inline message. Don't loop the skeleton.
Partial load. Skeleton only the unknown slices; keep stable headers and actions visible.

Best practices

Match border radius and spacing to the final components so the transition feels like a reveal.
Limit simultaneous skeleton count on low-end devices.

Don't

Skeleton an entire screen for a tiny optimistic update.
Use aggressive shimmer that reads as advertising chrome.

Accessibility

Skeleton regions don't trap focus. Prefer aria-busy on a container or a route-level announcement over per-element live regions. Ensure skeleton contrast is subtle but visible in both themes, and respect prefers-reduced-motion. See Accessibility for the full contract.

Loading indicator for indeterminate work.
Progress for determinate progress.
Data table for table-level loading patterns.

Sidebar / Accessibility

Skeleton / API and Development

On this page

Skeleton

Usage

Overview

When to use

Initial page or card load where structure is known but values are not.
Lists and tables where row height is predictable.
Any fetch that commonly exceeds a few hundred milliseconds and would otherwise show blank space.

When not to use

Very fast loads where the skeleton flashes—prefer no placeholder or a delay threshold.
Unknown layout. A neutral LoadingIndicator is clearer.
Background refresh where existing content stays valid—update in place rather than skeletonizing the whole view.
Indeterminate long processes with no layout—use Progress plus messaging.

Behavior and states

Show. After a short threshold if the request is still pending. Avoid sub-200 ms flashes.
Hide. Immediately when content is ready. A subtle cross-fade is acceptable.
Error. Replace the skeleton region with an error Banner or inline message. Don't loop the skeleton.
Partial load. Skeleton only the unknown slices; keep stable headers and actions visible.

Best practices

Match border radius and spacing to the final components so the transition feels like a reveal.
Limit simultaneous skeleton count on low-end devices.

Don't

Skeleton an entire screen for a tiny optimistic update.
Use aggressive shimmer that reads as advertising chrome.

Accessibility

Loading indicator for indeterminate work.
Progress for determinate progress.
Data table for table-level loading patterns.

Sidebar / Accessibility

Skeleton / API and Development

On this page