# Skeleton

A pulsing placeholder shown while content is loading.

- Category: Core Elements
- Page: https://wunderui.com/components/skeleton
- Tier: Free

## Install

```bash
npx wunderui-cli add skeleton
```

## Import

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

## Minimal usage

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.

## Usage

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

export function Example() {
  return (
    <div className="w-64 max-w-full">
      <Skeleton variant="text" />
    </div>
  )
}
```

## 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

- [Spinner](https://wunderui.com/components/spinner) for a short wait on an action, such as saving, or a panel without a known layout
- [Progress](https://wunderui.com/components/progress) for a task that reports how far it has come, such as an upload
- [Empty State](https://wunderui.com/components/empty-state) for a list that has loaded and has nothing in it

## Behavior

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

- `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

### When to use

- Use a Skeleton while content with a known layout loads: a list, a card, a profile. For a short wait on an action, such as saving, use a Spinner.

### 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.
- 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.
- Draw what you already know, such as the table header or the card title, and put placeholders only where data is missing.
- 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.
- 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 leave a skeleton on screen when loading fails. Replace it with an error message and a way to try again.
- Don't build your own placeholder for charts. They have a loading state that draws a skeleton of the right height.

## API reference

### Skeleton

| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "title" \| "text" \| "block" \| "avatar" | "block" | The shape of the placeholder: `text` for a line of body text, `title` for a heading, `avatar` for a round picture and `block` for an image or a chart. The default is `block`. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Layout: shapes put together to match the content

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

export function Example() {
  return (
    <div className="flex w-72 max-w-full flex-col gap-2">
      <Skeleton variant="text" />
      <Skeleton variant="text" />
      <Skeleton variant="text" className="w-3/5" />
    </div>
  )
}
```

### Size: width, avatar size and block height

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

export function Example() {
  return (
    <div className="flex w-72 max-w-full flex-col gap-3">
      <Skeleton variant="text" className="w-1/3" />
      <Skeleton variant="text" className="w-2/3" />
      <Skeleton variant="text" />
    </div>
  )
}
```

### Content state: the placeholder and the content take the same space

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

export function Example() {
  return (
    <div aria-busy="true" className="flex w-72 max-w-full items-center gap-3">
      <Skeleton variant="avatar" className="shrink-0" />
      <div className="flex min-w-0 flex-1 flex-col">
        <Skeleton variant="title" className="w-1/2" />
        <Skeleton variant="text" className="my-0.75 w-3/4" />
      </div>
      <span role="status" className="sr-only">
        Loading profile
      </span>
    </div>
  )
}
```

## In context

### Loading table: the header stays, the cells are placeholders

The columns are known before the data, so the header is drawn at once and only the cells wait. Switch to Loaded to see the same rows with data.

```tsx
import { Skeleton } from "@/components/ui/skeleton"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

export function Example() {
  return (
    <div aria-busy="true" className="w-full overflow-hidden rounded-xl border border-border bg-card">
      <Table aria-label="Recent customers">
        <TableHeader>
          <TableRow>
            <TableHead>Customer</TableHead>
            <TableHead>Plan</TableHead>
            <TableHead className="text-right">Amount</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          <TableRow>
            <TableCell><Skeleton variant="text" className="my-0.75 w-3/5" /></TableCell>
            <TableCell><Skeleton variant="text" className="my-0.75 w-12" /></TableCell>
            <TableCell><Skeleton variant="text" className="my-0.75 ml-auto w-16" /></TableCell>
          </TableRow>
          <TableRow>
            <TableCell><Skeleton variant="text" className="my-0.75 w-1/2" /></TableCell>
            <TableCell><Skeleton variant="text" className="my-0.75 w-12" /></TableCell>
            <TableCell><Skeleton variant="text" className="my-0.75 ml-auto w-16" /></TableCell>
          </TableRow>
          <TableRow>
            <TableCell><Skeleton variant="text" className="my-0.75 w-2/3" /></TableCell>
            <TableCell><Skeleton variant="text" className="my-0.75 w-12" /></TableCell>
            <TableCell><Skeleton variant="text" className="my-0.75 ml-auto w-16" /></TableCell>
          </TableRow>
          <TableRow>
            <TableCell><Skeleton variant="text" className="my-0.75 w-3/5" /></TableCell>
            <TableCell><Skeleton variant="text" className="my-0.75 w-12" /></TableCell>
            <TableCell><Skeleton variant="text" className="my-0.75 ml-auto w-16" /></TableCell>
          </TableRow>
        </TableBody>
      </Table>
      <span role="status" className="sr-only">
        Loading customers
      </span>
    </div>
  )
}
```

### KPI cards: one placeholder per line of the card

The label, the figure and the change each get a placeholder as tall as the text that replaces it, so the cards keep their height.

```tsx
import { Skeleton } from "@/components/ui/skeleton"
import { Card, CardContent } from "@/components/ui/card"

export function Example() {
  return (
    <div aria-busy="true" className="grid grid-cols-3 gap-6 max-sm:grid-cols-1 max-sm:gap-5">
      <Card>
        <CardContent className="flex flex-col gap-2">
          <Skeleton variant="text" className="my-0.75 w-1/2" />
          <Skeleton variant="title" className="h-8 w-3/5" />
          <Skeleton variant="text" className="my-px w-4/5" />
        </CardContent>
      </Card>
      <Card>
        <CardContent className="flex flex-col gap-2">
          <Skeleton variant="text" className="my-0.75 w-1/2" />
          <Skeleton variant="title" className="h-8 w-3/5" />
          <Skeleton variant="text" className="my-px w-4/5" />
        </CardContent>
      </Card>
      <Card>
        <CardContent className="flex flex-col gap-2">
          <Skeleton variant="text" className="my-0.75 w-1/2" />
          <Skeleton variant="title" className="h-8 w-3/5" />
          <Skeleton variant="text" className="my-px w-4/5" />
        </CardContent>
      </Card>
      <span role="status" className="sr-only">
        Loading figures
      </span>
    </div>
  )
}
```

### Member list: an avatar and two lines per row

Three rows stand for the list. The region says what is loading for assistive technology, because the placeholders are silent.

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

export function Example() {
  return (
    <div aria-busy="true" className="w-full overflow-hidden rounded-xl border border-border bg-card text-sm">
      <ul className="divide-y divide-border">
        <li className="flex items-center gap-3 px-4 py-3">
          <Skeleton variant="avatar" className="shrink-0" />
          <div className="flex flex-1 flex-col">
            <Skeleton variant="title" className="w-2/5" />
            <Skeleton variant="text" className="my-0.75 w-1/4" />
          </div>
        </li>
        <li className="flex items-center gap-3 px-4 py-3">
          <Skeleton variant="avatar" className="shrink-0" />
          <div className="flex flex-1 flex-col">
            <Skeleton variant="title" className="w-2/5" />
            <Skeleton variant="text" className="my-0.75 w-1/4" />
          </div>
        </li>
        <li className="flex items-center gap-3 px-4 py-3">
          <Skeleton variant="avatar" className="shrink-0" />
          <div className="flex flex-1 flex-col">
            <Skeleton variant="title" className="w-2/5" />
            <Skeleton variant="text" className="my-0.75 w-1/4" />
          </div>
        </li>
      </ul>
      <span role="status" className="sr-only">
        Loading members
      </span>
    </div>
  )
}
```

### Chart card: a title and a block the size of the plot

The block has the height of the chart, so the card does not grow when the bars are drawn.

```tsx
import { Skeleton } from "@/components/ui/skeleton"
import { Card, CardContent, CardHeader } from "@/components/ui/card"

export function Example() {
  return (
    <Card aria-busy="true" className="w-full">
      <CardHeader>
        <Skeleton variant="title" className="h-5.5 w-1/3" />
        <Skeleton variant="text" className="my-0.75 w-1/4" />
      </CardHeader>
      <CardContent>
        <Skeleton variant="block" className="h-40" />
      </CardContent>
      <span role="status" className="sr-only">
        Loading chart
      </span>
    </Card>
  )
}
```

## For AI agents

`get_component("skeleton")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
