Skeleton
FreeHold the place of content that is still loading, so the page keeps its shape.
npx wunderui-cli add skeletonPlayground
Installation
npx wunderui-cli add skeletonWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Skeleton } from "@/components/ui/skeleton"Then use it:
import { Skeleton } from "@/components/ui/skeleton"
export function MemberRowSkeleton() {
return (
<div aria-busy="true" className="flex w-72 items-center gap-3">
<Skeleton variant="avatar" className="shrink-0" />
<div className="flex flex-1 flex-col gap-2">
<Skeleton variant="title" className="w-1/2" />
<Skeleton variant="text" className="w-3/4" />
</div>
</div>
)
}Expected result: You see a grey circle with two grey bars beside it, a shorter one above a longer one, and a soft light band sweeping across all three from left to right about every two seconds.
When to use
Use Skeleton for
- Content with a known layout that loads, such as a table, a list of members or the cards of a dashboard
- The first load of a page or a panel, where an empty area would look broken
- A region that fills with data and should keep its size when it does
Use something else for
- Spinner for a short wait on an action, such as saving, or a panel without a known layout
- Progress for a task that reports how far it has come, such as an upload
- Empty State for a list that has loaded and has nothing in it
Layout
Build the placeholder from the four shapes so it has the structure of the content: lines of text with a shorter last line, an avatar beside two lines, a block above a title.
Size
Each shape comes with a size and a radius. Match the size of the real content: a width for a line, a size for an avatar, a height for a block.
w-1/3w-2/3full widthsize-840 pxsize-14h-16100 pxh-32Content state
Swap the placeholder for the content in the same space. A placeholder as tall as the line it stands for keeps the page from jumping when the data arrives.
Nora Lindgren
Product designer at WunderUI
Behavior and motion
What the placeholder does with shape, size, motion and assistive technology.
- Shapes
- Text is a full-width line with a 4 px radius, and title is a taller line two thirds wide. Avatar is a 40 px circle, and block, the default, is a 100 px box with an 8 px radius.
- Size
- The shape only sets a default. Add a width, height or size in a class to match the content, since your class is applied after the shape.
- Line height
- A normal text line is 20 px high and the text shape is 14 px. A 3 px margin above and below makes the placeholder as tall as the line, so the layout does not move when the text arrives.
- Shimmer
- The bar uses the muted colour. A highlight, 6 % foreground (10 % in dark mode), sweeps across from left to right every 1.8 seconds, without end.
- Accessibility
- The Skeleton is a plain div with no role or name, and it is not announced. Mark the loading region as busy and add a visually hidden status element that says what is loading.
- Theme
- The colours are tokens, so the bar and highlight follow the theme. The highlight is a little stronger in dark mode so it stays visible on the darker bar.
- Motion
- Only the highlight moves. The size, layout and bar colour never animate.
- Reduced motion
- With reduced motion the highlight is not drawn. The grey bar stays, so the loading state is still visible, just still.
Anatomy
The Skeleton is one element. The figure marks the placeholder of a media card, and every shape is the same part with another size and radius.
- 1data-slot="skeleton"
A grey placeholder with a soft sweeping highlight, as a 14 px text line, 20 px title line, 40 px avatar circle or 100 px block. It has no role or label and is still under reduced motion.
Best practices
- Do
Give each Skeleton the size of the content it stands for. The layout then keeps its height and does not jump when the content arrives.
- Do
Make a text placeholder as tall as the line it stands for. The text shape is 14 px high and a normal line is 20 px, so add 3 px of margin above and below.
- Do
Draw what you already know, such as the table header or the card title, and put placeholders only where data is missing.
- Do
Mark the loading region as busy and remove that when the content is in. Add a visually hidden status line saying what is loading, because the placeholders say nothing to screen readers.
- Do
Show a skeleton for the first load only. When data refreshes, keep the old content on screen and update it in place.
- Don’t
Don't fill the whole screen with blocks. Cover what is visible when the page opens and let the rest render with its data.
- Don’t
Don't leave a skeleton on screen when loading fails. Replace it with an error message and a way to try again.
- Don’t
Don't build your own placeholder for charts. They have a loading state that draws a skeleton of the right height.
API reference
One table for the one part. Skeleton also takes every prop of the div it renders, such as className, style and aria-busy.
A grey placeholder with a soft sweeping highlight, as a 14 px text line, 20 px title line, 40 px avatar circle or 100 px block. It has no role or label and is still under reduced motion.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "title" | "text" | "block" | "avatar" | "block" | The shape of the placeholder: for a line of body text, for a heading, for a round picture and for an image or a chart. The default is . |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("skeleton")npx wunderui-cli add skeletonThe full library index for assistants is at /llms.txt.