Skeleton
A loading state drawn from the content's own layout. While data loads, the real content is laid out unseen, a bar is drawn over each line of text and a block over each image and control, and the content takes the bars' place when it arrives, so nothing moves. A page imports this wrapper, never the skeleton package behind it.
Not drawn here
A skeleton is measured in the browser by a script that runs before the first paint, so it cannot be drawn on a page that ships no script. This site ships none beyond its shell, so there is no live example. See the Components / Skeleton stories in Storybook for the loading state in light and dark.
Code
TSX
<SkeletonProvider nonce={nonce}>
<Skeleton data={listing} sample={SAMPLE_LISTING} label="Loading your listing">
{(listing) => <ListingCard listing={listing} />}
</Skeleton>
</SkeletonProvider>Put one SkeletonProvider around the part of a page that uses a skeleton, never in a root or shared layout, and pass the page's CSP nonce if its policy names one. Call forgetSkeletonShapes() when someone signs out. No page uses it yet.
Variants
| Prop | Value | How it looks |
|---|---|---|
| bar fill | track role | The track role: ink 14% light, ground 18% dark. The same rail the scroll area's thumb uses. |
| shimmer band | page role in light, text role in dark | The page role at 70% in light, the text role at 12% in dark, chosen with light-dark() from the document's colour scheme. |
| radius | 4px | Every text line and box; images and chips keep their own. |
| motion | slow shimmer | One highlight sweeps every skeleton on the page together, looping in 4 seconds. |
States
| State | How it looks |
|---|---|
| loading | Bars over the content's layout. The container is aria-busy, and the skeleton is aria-hidden and inert; the label is read in its place. |
| loaded | The content crossfades in over the bars (smart reveal: at once for a load under 150ms, so a fast load shows no skeleton). |
| reduced motion | The shimmer and the fades hold still; the bars stay. |
| forced colours | Each bar is drawn in GrayText with no shimmer band, so it stays visible in a contrast theme. |
| no script | Each line of text is struck through with a bar instead. The server render measures the skeleton in an inline script before first paint, once per page under the provider. |
| error | The error node replaces the content. |
Props
Import from @repo/ui/skeleton.
| Prop | Type | Default | What it does |
|---|---|---|---|
| children | (data: T) => ReactNode, or ReactNode with loading | default required | The content. A function receives the data once it has arrived. |
| label | string | default required | What a screen reader reads while the skeleton is up, such as "Loading your listing". The skeleton itself is hidden from it. |
| data | T | null | undefined | Loading while empty (null or missing); passed to children once it is not. | |
| sample | T | A made-up value of the same shape, which the first skeleton is drawn from. | |
| loading | boolean | Shows the skeleton while true. Required when children is not a function; with data, it also shows the skeleton over data, such as while refetching. | |
| id | string | Names the block for shape recall within one page session. Nothing is kept on the device, so a new visit draws its first skeleton from sample. | |
| error | ReactNode | Shown instead of the content when set. | |
| className | string | Classes for the container. | |
| onReveal | () => void | Called once content has come in over a skeleton. | |
| nonce | string | On SkeletonProvider: the page's CSP nonce, set on the inline script and the styles the skeleton writes. |
Use it well
Give a skeleton a sample of the same shape as the real data, with made-up words, so its bars have the right lengths. Never sample from a real person's content.
Pass the nonce on a page whose policy names one. A policy with 'unsafe-inline' needs none.
Call forgetSkeletonShapes() on sign-out: the shapes the page remembers in memory hold the real, unmasked text it showed.
Give images a size or an aspect ratio, or the content moves once they load.
Don't: Do not put the provider in a root or shared layout: it would load the skeleton for pages that never draw one.