Fair Case

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

Variants
PropValueHow it looks
bar filltrack roleThe track role: ink 14% light, ground 18% dark. The same rail the scroll area's thumb uses.
shimmer bandpage role in light, text role in darkThe page role at 70% in light, the text role at 12% in dark, chosen with light-dark() from the document's colour scheme.
radius4pxEvery text line and box; images and chips keep their own.
motionslow shimmerOne highlight sweeps every skeleton on the page together, looping in 4 seconds.

States

States
StateHow it looks
loadingBars 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.
loadedThe content crossfades in over the bars (smart reveal: at once for a load under 150ms, so a fast load shows no skeleton).
reduced motionThe shimmer and the fades hold still; the bars stay.
forced coloursEach bar is drawn in GrayText with no shimmer band, so it stays visible in a contrast theme.
no scriptEach 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.
errorThe error node replaces the content.

Props

Import from @repo/ui/skeleton.

Props
PropTypeDefaultWhat it does
children(data: T) => ReactNode, or ReactNode with loadingdefault requiredThe content. A function receives the data once it has arrived.
labelstringdefault requiredWhat a screen reader reads while the skeleton is up, such as "Loading your listing". The skeleton itself is hidden from it.
dataT | null | undefinedLoading while empty (null or missing); passed to children once it is not.
sampleTA made-up value of the same shape, which the first skeleton is drawn from.
loadingbooleanShows the skeleton while true. Required when children is not a function; with data, it also shows the skeleton over data, such as while refetching.
idstringNames 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.
errorReactNodeShown instead of the content when set.
classNamestringClasses for the container.
onReveal() => voidCalled once content has come in over a skeleton.
noncestringOn 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.