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.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque felis tellus, efficitur id convallis a, viverra eget libero. Nam magna erat, fringilla sed commodo sed, aliquet nec magna.
- 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.
- 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.
- 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
Callout or inline message. Don't loop the skeleton.
- Partial load. Skeleton only the unknown slices; keep stable headers and actions visible.
Do
- 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.
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.
