---
title: "Skeleton"
description: "A grey placeholder in the shape of the content that is loading, so the page does not jump when it arrives. It is never in the shape of a number."
url: "https://opsinjs.pensievelabs.org/docs/components/skeleton"
source: "https://opsinjs.pensievelabs.org/docs/components/skeleton.md"
section: "Components"
status: "shipped"
kind: "component"
category: "feedback"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["loading placeholder", "shimmer", "loading state", "placeholder", "ghost"]
governedBy: ["alerts", "trends"]
usedIn: ["empty-and-first-use", "trend-review"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="skeleton"
  status="shipped"
  questions="[
  &#x22;Nothing in opsinjs owns the long end of a wait: past the few seconds Data states allows, a skeleton should have become words, and no threshold is measured.&#x22;,
  &#x22;Shimmer defaults to on because a motionless rectangle can read as stalled content, and nobody has watched an anxious reader look at either state.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="skeleton" unbuilt="false" importPath="@/components/ui/skeleton" />

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

```tsx
<Skeleton shape="text" lines={3} appearAfterMs={200} />
```

## Examples [#examples]

<ComponentPreview name="skeleton" />

### A list that is still arriving [#a-list-that-is-still-arriving]

Three rows of `aria-hidden` skeletons, with one polite `role="status"` message the
caller mounts beside the busy list rather than inside it. Every skeleton passes
`appearAfterMs`, so a warm cache never shows one.

<ComponentPreview name="skeleton-a-loading-list" kind="example" align="start" />

### A row that may turn out to be empty [#a-row-that-may-turn-out-to-be-empty]

The label gets a placeholder because every row has one. The value's seat gets
height and no shape, because whether a reading exists is what the request will
answer.

<ComponentPreview name="skeleton-a-row-that-may-be-empty" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Content whose size and position are known in advance, arriving within roughly a second, where the alternative is the layout jumping when it lands.&#x22;,
  &#x22;Lists and grids where a known number of items is loading and the reader benefits from seeing the shape of what is coming.&#x22;,
  &#x22;Any surface where a spinner would replace a whole screen with nothing.&#x22;,
]"
  avoid="[
  { case: &#x22;There is nothing coming. The surface is genuinely empty.&#x22;, instead: &#x22;empty-state&#x22; },
  { case: &#x22;Loading did not complete.&#x22;, instead: &#x22;alert-banner&#x22; },
  { case: &#x22;The wait is long enough that the reader needs to know it is a long wait.&#x22;, instead: &#x22;callout&#x22; },
  { case: &#x22;The shape and size of what is coming are unknown, so the skeleton would guess.&#x22;, instead: &#x22;spinner&#x22; },
  { case: &#x22;A single control is busy after the reader pressed it.&#x22;, instead: &#x22;button&#x22; },
]"
/>

## Accessibility [#accessibility]

Rendered, it shows no violation, target-size hit, missing focus-visible state or
reflow failure at 320px, and the audit changed nothing. On every commit
`pnpm run check:a11y` checks that no status colour can reach a skeleton, that every
colour is a theme role (`bg-placeholder-fill`, `border-placeholder-line`), and that no
type size is in `px`. `pnpm run contrast` measures the placeholder line clearing the
non-text floor against the page, a card and the muted ground in both themes.

**Argued from the source, not measured.**

* The root is `aria-hidden`, nothing is focusable or interactive, and it is
  `print:hidden`.
* No live region mounts, on purpose. A list of many skeletons should be announced once,
  not once per block, so the caller owns one `role="status"` message beside the region
  rather than inside it, as both examples show.
* The shimmer is declared inside a `prefers-reduced-motion: no-preference` query, so
  under reduce it never runs and the static tint remains.
* The shimmer runs two cycles, about 3.2 seconds, then stops on the static tint, so
  SC 2.2.2 does not engage. The appearance delay is never suppressed.
* There is no `forced-colors` or `prefers-contrast` override, because the decorative,
  `aria-hidden` root has no information an override would need to preserve.

**Residual items.** `pnpm run contrast` puts the placeholder line below Lc 45 against
its own fill in the dark theme, and the fill is published as advisory. No gate checks
the 200% and 1.3x layout claims, what a screen reader announces, the dark-theme
boundary on its own fill, or the text rhythm on a browser without the `lh` unit.

<KeyboardTable
  name="skeleton"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Skips the skeleton&#x22;,
    notes: &#x22;Nothing inside one is focusable. A stop that vanishes on load is worse than none.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Skips the skeleton&#x22;,
    notes: &#x22;Same in reverse, at any shape, with or without the shimmer.&#x22;,
  },
]"
/>

<ContrastReport component="skeleton" />

## Props interface [#props-interface]

<PropsTable name="SkeletonProps" />

`Skeleton` is a server component: `appearAfterMs` is a CSS `animation-delay`,
not a timer, so the placeholder holds the layout before hydration. A `shape`
outside the four resolves to `text`. `lines` is clamped to 1 to 24. No part is
exported; style them through `data-slot`.
