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
skeleton · base base · style base-lyraOpen under the product themeA 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.
skeleton-a-loading-list · base base · style base-lyraOpen under the product themeimport { 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.
skeleton-a-row-that-may-be-empty · base base · style base-lyraOpen under the product themeimport 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-stateinstead. - Loading did not complete.Use
alert-bannerinstead. - The wait is long enough that the reader needs to know it is a long wait.Use
calloutinstead. - The shape and size of what is coming are unknown, so the skeleton would guess.Use
spinnerinstead. - A single control is busy after the reader pressed it.Use
buttoninstead.
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 isprint: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-preferencequery, 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-colorsorprefers-contrastoverride, because the decorative,aria-hiddenroot 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.
| Key | Action | Notes |
|---|---|---|
| Tab | Skips the skeleton | Nothing inside one is focusable. A stop that vanishes on load is worse than none. |
| Shift+Tab | Skips the skeleton | Same in reverse, at any shape, with or without the shimmer. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below 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.