Skip to content
WunderUI

Skeleton

Free

Hold the place of content that is still loading, so the page keeps its shape.

npx wunderui-cli add skeleton

Playground

Installation

bash
npx wunderui-cli add skeleton

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import { Skeleton } from "@/components/ui/skeleton"

Then use it:

tsx
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/3
w-2/3
full width

Content 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.

Loading profile

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.

  • data-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.

PropTypeDefaultDescription
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.

MCPget_component("skeleton")
Installnpx wunderui-cli add skeleton

The full library index for assistants is at /llms.txt.