Skip to content
opsinjs
Edit this page

Components

Skeleton

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.

Usage

pnpm dlx shadcn@latest add @opsinjs/skeleton

The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.

import { Skeleton } from "@/components/ui/skeleton"
<Skeleton shape="text" lines={3} appearAfterMs={200} />

Examples

Theme
Density
Text
Status
Accent theme
Accent
skeleton · base base · style base-lyraOpen under the product theme

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.

Theme
Density
Text
Status
Accent theme
Accent
skeleton-a-loading-list · base base · style base-lyraOpen under the product theme
skeleton-a-loading-list.tsx
import { Skeleton } from "@/components/ui/skeleton"

const ROWS = ["first", "second", "third"]

/* This example's own choice, and nothing more. `foundations/data-states` names
   a floor. Below roughly a tenth of a second a skeleton is worse than nothing,
   because the flash reads as a glitch. The doc then says the number itself
   is a product decision. This is one, made for a list of three rows, not a
   figure opsinjs holds: opsinjs owns no thresholds of any kind. Pick your own
   from what the request actually costs. */
const APPEAR_AFTER_MS = 200

export default function SkeletonALoadingList() {
  return (
    <section className="flex w-full max-w-md flex-col gap-opsin-4">
      {/* One message for the whole region, polite, and never one per row. It is
          `sr-only` because a sighted reader already has the answer: the shapes
          are the answer. It is a SIBLING of the busy list rather than a child of
          it, because a live region inside an `aria-busy` element is suppressed
          for as long as the element stays busy. */}
      <p role="status" className="sr-only">
        Loading example items
      </p>

      {/* The part that is still settling. A reader who arrives mid-load is not
          walked through a list of nothing; when the content lands, the product
          clears this. */}
      <div aria-busy="true" className="flex flex-col gap-opsin-4">
        {ROWS.map((row) => (
          <div
            key={row}
            className="flex items-start gap-opsin-3 border-b border-border pb-opsin-3"
          >
            {/* The avatar's seat. It is a circle because a circle is coming,
                and for no other reason. A shape chosen to fill space rather
                than to match what lands is where the layout shift comes back. */}
            <Skeleton
              shape="circle"
              appearAfterMs={APPEAR_AFTER_MS}
              className="shrink-0"
            />
            <div className="flex min-w-0 grow flex-col gap-opsin-2 text-opsin-body">
              {/* The title: one line, full width, never shortened. */}
              <Skeleton
                shape="line"
                appearAfterMs={APPEAR_AFTER_MS}
                className="w-1/2"
              />
              {/* The description: two lines of body text, the last one short.
                  The bars now reserve one inherited line box each, so the row
                  declares its type step with `text-opsin-body` above. That is
                  the part worth copying: the placeholder and the text that lands
                  are demonstrably the same size because both read the same step,
                  rather than the reservation happening to match at the body
                  step and drifting everywhere else. */}
              <Skeleton shape="text" lines={2} appearAfterMs={APPEAR_AFTER_MS} />
            </div>
          </div>
        ))}
      </div>
    </section>
  )
}

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.

Theme
Density
Text
Status
Accent theme
Accent
skeleton-a-row-that-may-be-empty · base base · style base-lyraOpen under the product theme
skeleton-a-row-that-may-be-empty.tsx
import type { ReactNode } from "react"

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

function Panel({
  caption,
  children,
}: {
  caption: string
  children: ReactNode
}) {
  return (
    <div className="flex min-w-0 basis-full flex-col gap-opsin-2 sm:grow sm:basis-0">
      <p className="m-0 font-mono text-opsin-caption1 text-muted-foreground">
        {caption}
      </p>
      <div className="flex flex-col gap-opsin-1 rounded-opsin-md border border-border bg-card p-opsin-4">
        {children}
      </div>
    </div>
  )
}

export default function SkeletonARowThatMayBeEmpty() {
  return (
    <div className="flex w-full max-w-lg flex-wrap gap-opsin-4">
      <Panel caption="loading">
        {/* The label is certain to arrive, so it gets a placeholder. The step
            goes on the root because the bar is `1em` of the font size it
            inherits, and the root is what the caller can reach: this is the
            repair the component's own JSDoc asks the caller to make, so that the
            bar and the resolved label are the same line. */}
        <Skeleton shape="line" className="w-2/3 text-opsin-footnote" />
        {/* The value is not certain to arrive, so it gets height and no shape.
            The step matches the resolved seat so the identical `1.75em`
            reservation resolves against the identical font size on both sides. */}
        <div className="min-h-[1.75em] text-opsin-headline" />
      </Panel>

      <Panel caption="resolved">
        <p className="m-0 text-opsin-footnote text-muted-foreground">
          Example measurement
        </p>
        {/* Words, never `0` and never a dash: an absent reading and a reading of
            zero are different facts about a person. `data-opsinjs-value=""` is
            the empty-string form the attribute takes when the value is null, so
            an absence is as greppable as a number. In a product this seat is the
            Value component, and the attribute comes from it. It is written by
            hand here only because this example is about the SHAPE of the seat
            and imports nothing but Skeleton. */}
        <p
          data-opsinjs-value=""
          className="m-0 min-h-[1.75em] text-opsin-headline"
        >
          No reading yet
        </p>
      </Panel>
    </div>
  )
}

When to use it

Use it when

  • Content whose size and position are known in advance, arriving within roughly a second, where the alternative is the layout jumping when it lands.
  • Lists and grids where a known number of items is loading and the reader benefits from seeing the shape of what is coming.
  • Any surface where a spinner would replace a whole screen with nothing.

Do not use it when

  • There is nothing coming. The surface is genuinely empty.Use empty-state instead.
  • Loading did not complete.Use alert-banner instead.
  • The wait is long enough that the reader needs to know it is a long wait.Use callout instead.
  • The shape and size of what is coming are unknown, so the skeleton would guess.Use spinner instead.
  • A single control is busy after the reader pressed it.Use button instead.

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.

KeyActionNotes
TabSkips the skeletonNothing inside one is focusable. A stop that vanishes on load is worse than none.
Shift+TabSkips the skeletonSame in reverse, at any shape, with or without the shimmer.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor

These are the measured token pairs this component draws colour from, not a measurement of the component itself.

Props interface

Prop

Type

Generated from SkeletonProps in registry/bases/base/skeleton.tsx.

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.