Skeleton
Preview appears after the next Storybook update.
<Skeleton />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.
Content guidelines
- The hidden loading label names the content: "Loading tokens", not "Loading...".
From the code Generated from the component, not editable here.
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
Motion and interaction
Skeleton loops while it is shown. Try it in the preview at the top.
| When | What changes | Duration | Easing |
|---|---|---|---|
| While shown | Loops (shimmer) | motion.duration.shimmer1400 ms | Part of the loop |
With reduced motion turned on, the loop stops.
From the code Generated from the component, not editable here.
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 variant="circle" />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
From the code Generated from the component, not editable here.
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
v1.0.0, Nov 11, 2026
- Fix
Skeleton docs: the preview shows an avatar, two text lines and a block (it rendered at zero width)
v1.0.0, Nov 11, 2026
- Fix
Component pages: the On this page rail sits on the right from the top of the page (from 1320px) instead of inside the reading column, and the Skeleton preview shows an avatar, two lines and a block
v1.0.0, Nov 11, 2026