Skeleton
StableA placeholder in the shape of content that is loading, so the layout does not jump when the data arrives.
When to use
Use it for
- First load of a list, table, card or detail panel whose shape you know.
- Mirror the real layout: a circle for an avatar, short lines for names, a block for a preview.
- Pair with aria-busy="true" on the region and a visually hidden "Loading tokens".
Not for
- Inside a button or after a click on a control: use Button loading or Spinner.
- Long tasks with known progress: use Progress.
- When loading takes under about 300 ms: show nothing, the flash is worse than the wait.
Do and don't
Every example is rendered with the real component, so it always matches what ships.
Match the shape of the real content
The page settles in place instead of reflowing when data lands.
A whole page of shimmering blocks
Load the frame (navigation, titles) for real and use skeletons only where the data goes.
Accessibility
- Skeletons are always aria-hidden: they are decoration, not content.
- Put aria-busy="true" on the loading region and a VisuallyHidden label like "Loading tokens"; remove both when the content arrives.
- The shimmer stops under prefers-reduced-motion; use static for long lists.
Anatomy and tokens
Read from packages/react/src/components/Skeleton/Skeleton.module.css at build time. Every value is a token: open one to see its
alias chain in both themes.
- Block
.skeleton - Circle (avatar)
.circle - Block (media, card)
.rect
Props
Parsed from the TypeScript types in packages/react/src/components/Skeleton/Skeleton.tsx, so this table cannot drift from the
code.
It also accepts every native <span> attribute.
| Prop | Type | Default | Description |
|---|---|---|---|
variant | 'text' | 'circle' | 'rect' | 'text' | `text` draws lines at the current font size; `circle` an avatar; `rect` a block (thumbnail, chart, card). Default `text`. |
lines | number | 1 | Number of text lines. The last one is shorter, like a real paragraph. Default 1. |
width | string | none | CSS width, for example `"12ch"` or `"100%"`. Defaults: text 100%, circle 40px, rect 100%. |
height | string | none | CSS height for `rect` and `circle`. |
static | boolean | none | Stop the shimmer (for example in long lists). Reduced motion stops it everywhere. |
Playground
Change the props and see the real Skeleton update. Controls are generated from the TypeScript props; nothing here changes the system.
<Skeleton />Workbench
For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open Skeleton in Storybook) .
Embed Storybook stories here (4)
Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay
empty.
Text
Circle
Rect
AllStates
Changelog
- New
Feedback: Alert (five tones, actions, dismiss, correct live region), Toast (ToastProvider and useToast with success, error, warning, info, promise, update and close), Progress (linear and circular, determinate and indeterminate), Skeleton, EmptyState, plus Spinner stories and guidance. Adds alert and skeleton component tokens.
Unreleased (current version 0.1.0, no release tagged yet) , Oct 17, 2026