Skeleton
An animated placeholder for loading states.
Installation
$
npx shadcn@latest add https://ui.mattdowney.com/r/skeleton.jsonUsage
import { Skeleton, SkeletonText, SkeletonReveal } from "@/components/ui/skeleton"Examples
Default
Placeholder blocks in the shape of what is loading. Size each one with className, and match the real layout: that is what stops the page jumping when the content lands.
Text
Lines of text still loading. Set the type the real text will have: each line takes that line height, so the swap does not jump and a control beside the first line stays put.
Reveal
When loading ends, the content fades in as the placeholder fades out, so there is no blank beat. Shape the placeholder like the content and the box does not move. Press Load again to replay it.
API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
| stillSkeleton | boolean | false | Turns the pulse off. The pulse means loading; use still when the blocks are the picture itself, such as a wireframe thumbnail of a page. |
| linesSkeletonText | number | 3 | How many lines. The last of several stops at two thirds, like a paragraph. |
| loadedSkeletonReveal | boolean | None | False shows placeholder. True fades the content in and the placeholder out together over 200ms; at once under reduced motion. |
| placeholderSkeletonReveal | ReactNode | None | What shows while loading, in the content's shape: Skeleton blocks or SkeletonText. |
stillSkeletonboolean = falseTurns the pulse off. The pulse means loading; use still when the blocks are the picture itself, such as a wireframe thumbnail of a page. |
| linesSkeletonTextnumber = 3How many lines. The last of several stops at two thirds, like a paragraph. |
loadedSkeletonRevealbooleanFalse shows placeholder. True fades the content in and the placeholder out together over 200ms; at once under reduced motion. |
| placeholderSkeletonRevealReactNodeWhat shows while loading, in the content's shape: Skeleton blocks or SkeletonText. |
import { cn } from "@/registry/lib/utils"
// @use-when a placeholder block held in position while real content loads;
// for lines of text, SkeletonText, which keeps the text's own line height;
// SkeletonReveal fades the content in as the placeholder fades out when loading ends.
function Skeleton({
still = false,
className,
...props
}: React.ComponentProps<"div"> & {
/** No pulse. The pulse says "loading"; a block that is the picture itself
* (a wireframe, a page thumbnail) holds still. */
still?: boolean
}) {
return (
<div
data-slot="skeleton"
className={cn(
"bg-neutral-200 dark:bg-neutral-800 rounded-md",
!still && "animate-pulse motion-reduce:animate-none",
className
)}
{...props}
/>
)
}
// Lines of text that have not loaded yet. Each line is one line box of the
// surrounding type (`h-lh`) with a bar centred in it, so the stack is exactly as
// tall as the text that replaces it and nothing jumps on the swap. It also
// means a control beside the first line (a refresh button, a kebab) centres on
// the same line in both states. Set the type on this element or its parent the
// way the real text sets it: the line height comes from there, not from here.
// The bar is 0.71em, Geist's cap height, so it reads as a line of capitals and
// scales with the type. The last line stops at two thirds, like a paragraph.
function SkeletonText({
lines = 3,
className,
...props
}: React.ComponentProps<"div"> & { lines?: number }) {
const count = Math.max(1, Math.floor(lines))
return (
<div data-slot="skeleton-text" aria-hidden className={cn("w-full", className)} {...props}>
{Array.from({ length: count }, (_, i) => (
<div key={i} className="flex h-lh items-center">
<Skeleton className={cn("h-[0.71em] w-full", count > 1 && i === count - 1 && "w-2/3")} />
</div>
))}
</div>
)
}
// The handover from placeholder to content, as one cross-fade on the large
// role (200ms): the content arrives while the placeholder leaves, so there is
// never an empty frame. The content also sharpens from a 2px blur, which reads
// as it coming into focus. Both layers share one duration and curve, because
// they are one change.
//
// While loading, the placeholder holds the box. When `loaded` turns true the
// content takes the box and the placeholder lifts out of the flow
// (`absolute inset-0`) and fades over it, so the height is the content's from
// the first frame. Give the placeholder the content's shape (SkeletonText for
// text) and nothing moves. The content's entrance is `@starting-style`
// (`starting:`), so it needs no effect and works in a Server Component; the
// placeholder stays mounted but invisible and out of the accessibility tree.
// Reduced motion swaps at once.
const revealMove = "transition-[opacity,filter,visibility] duration-large ease-large motion-reduce:transition-none"
function SkeletonReveal({
loaded,
placeholder,
className,
children,
...props
}: React.ComponentProps<"div"> & {
/** False shows `placeholder`; true fades it out and `children` in. */
loaded: boolean
/** What shows while loading, shaped like the content: Skeleton blocks or SkeletonText. */
placeholder: React.ReactNode
}) {
return (
<div data-slot="skeleton-reveal" data-loaded={loaded || undefined} className={cn("relative", className)} {...props}>
{loaded && <div className={cn(revealMove, "opacity-100 starting:opacity-0 starting:blur-2xs")}>{children}</div>}
<div
aria-hidden={loaded || undefined}
className={cn(revealMove, loaded && "pointer-events-none invisible absolute inset-0 overflow-hidden opacity-0")}
>
{placeholder}
</div>
</div>
)
}
export { Skeleton, SkeletonText, SkeletonReveal }