When to use
- Content loading into a layout you already know: a profile header, a list of rows, a card's text.
- Wrapping the real component while its data loads, so the placeholder is exactly its size and nothing shifts at the handoff.
- Several placeholders on one screen, which should shimmer as one band rather than each on its own beat.
When not to use
Installation
pnpm dlx shadcn add https://eased.dev/r/skeleton.jsonnpx shadcn add https://eased.dev/r/skeleton.jsonyarn dlx shadcn add https://eased.dev/r/skeleton.jsonbunx --bun shadcn add https://eased.dev/r/skeleton.jsonThe command adds Skeleton, everything it builds on and Eased’s tokens to your project.
Install the dependencies
pnpm add motionnpm install motionyarn add motionbun add motionAdd the Eased pieces it builds on
Copy each item’s files the same way, or install them with the CLI:
Copy the source into your project
components/eased/skeleton/skeleton.tsxTSX "use client";import { AnimatePresence, motion, type TargetAndTransition } from "motion/react";import { useLayoutEffect, useRef, type ReactNode } from "react";import { enter, exit, reducedFade, useSafeReducedMotion } from "../lib/motion";export type SkeletonProps = { /** While true the shimmer shows; set it false and the shimmer hands off to `children`. Default true. */ loading?: boolean; /** * The real content. While loading it is laid out but invisible (and inert), so the * placeholder is exactly its size and nothing shifts at the handoff. Pass stand-in text * of a typical length while the data is missing, e.g. `{user?.name ?? "Maya Okafor"}`. * Without children the skeleton is a plain block: size it with `className`. */ children?: ReactNode; /** Size and radius classes. Default radius `rounded-control-xs`; pass `rounded-pill` for avatars. */ className?: string; /** Lay the wrapper out as a block (`grid`) instead of inline, for cards and rows. Default false. */ block?: boolean; /** * Wrapping text: the bar covers the middle 60% of each line box (roughly the x-height plus * ascenders) instead of the full line height, so it reads as a line of text. Default false. */ text?: boolean;};/* * One shimmer for the whole page: the highlight is painted in viewport space * (background-attachment: fixed) and every skeleton's animation is pinned to the same start * time, so a single band sweeps across all of them in sync instead of each one flashing on * its own beat. The highlight is the base tone lifted 6% in lightness, in both themes. */const CSS = `@keyframes eased-shimmer { from { background-position: -170vw 0; } 70%, to { background-position: -30vw 0; } }.eased-skeleton { background-color: var(--eased-surface-hover); background-image: linear-gradient(90deg, transparent 46%, oklch(from var(--eased-surface-hover) calc(l + 0.06) c h) 50%, transparent 54%); background-size: 300vw 100%; background-attachment: fixed; background-repeat: no-repeat; animation: eased-shimmer 2000ms linear infinite;}@media (prefers-reduced-motion: reduce) { .eased-skeleton { animation: none; background-image: none; } }`;/** Pins every running shimmer to the document timeline's zero, so they share one phase. */function useSharedPhase<T extends HTMLElement>() { const ref = useRef<T>(null); useLayoutEffect(() => { for (const a of ref.current?.getAnimations() ?? []) a.startTime = 0; }, []); return ref;}/** * A loading placeholder with one page-wide shimmer. Wrap the real content and flip * `loading` off: the shimmer fades out as the content fades in from a soft blur, in place. */export function Skeleton({ loading = true, children, className = "", block = false, text = false }: SkeletonProps) { const reduced = useSafeReducedMotion(); const radius = /\brounded-/.test(className) ? "" : "rounded-control-xs"; if (children === undefined) { return ( <AnimatePresence initial={false}> {loading && ( <Block key="block" className={`block ${radius} ${className}`} exit={{ opacity: 0, transition: reduced ? reducedFade : exit }} /> )} </AnimatePresence> ); } return ( <span aria-busy={loading || undefined} className={`relative ${block ? "grid" : "inline-grid"} max-w-full ${className}`}> <motion.span inert={loading} className="col-start-1 row-start-1 min-w-0" initial={false} animate={ loading ? { opacity: 0, filter: reduced ? "blur(0px)" : "blur(4px)" } : { opacity: 1, filter: "blur(0px)", transitionEnd: { filter: "none" } } } transition={reduced ? reducedFade : loading ? { duration: 0 } : enter} > {children} </motion.span> <AnimatePresence initial={false}> {loading && ( <Block key="block" className={`absolute ${text ? "inset-x-0 inset-y-[0.2lh]" : "inset-0"} ${radius} ${className.match(/\brounded-\S+/g)?.join(" ") ?? ""}`} exit={{ opacity: 0, transition: reduced ? reducedFade : exit }} /> )} </AnimatePresence> </span> );}function Block({ className, exit: exitTo }: { className: string; exit: TargetAndTransition }) { const ref = useSharedPhase<HTMLSpanElement>(); return ( <motion.span ref={ref} aria-hidden className={`eased-skeleton ${className}`} exit={exitTo}> <style href="eased-skeleton" precedence="default"> {CSS} </style> </motion.span> );}export type SkeletonTextProps = { /** Number of lines. Default 3; the last one is shorter, like a paragraph's. */ lines?: number; loading?: boolean; className?: string;};/** Lines sized for 13–14px text: 12px bars on a 20px rhythm. */export function SkeletonText({ lines = 3, loading = true, className = "" }: SkeletonTextProps) { return ( <span aria-hidden className={`flex flex-col gap-2 py-1 ${className}`}> {Array.from({ length: lines }, (_, i) => ( <Skeleton key={i} loading={loading} className={`h-3 ${i === lines - 1 && lines > 1 ? "w-3/5" : "w-full"}`} /> ))} </span> );}Keep the folder layout
The files import each other by relative path (
../lib/motion), so keep each one at the path shown, undercomponents/eased/.
Usage
Wrap the real content and pass loading. While data is missing, render stand-in text of a typical length so the placeholder takes its size.
import { Avatar } from "@/components/eased/avatar/avatar";import { Skeleton } from "@/components/eased/skeleton/skeleton";export function ProfileHeader({ user }: { user?: { name: string; role: string; photo: string } }) { return ( <div className="flex items-center gap-3"> <Skeleton loading={!user} className="rounded-pill"> <Avatar name={user?.name ?? "Maya Okafor"} src={user?.photo} /> </Skeleton> <div className="flex flex-col"> <Skeleton loading={!user} text> <p className="text-ui font-medium">{user?.name ?? "Maya Okafor"}</p> </Skeleton> <Skeleton loading={!user} text> <p className="text-ui-sm text-text-muted">{user?.role ?? "Product designer"}</p> </Skeleton> </div> </div> );}Examples
Plain blocks
Without children a skeleton is a block; size and round it with classes.
<Skeleton className="h-24 w-full rounded-panel" />Paragraph
SkeletonText draws lines sized for 13–14px text, the last one shorter.
<SkeletonText lines={4} loading={!summary} />API reference
Skeleton
| Prop | Type | Default | Description |
|---|---|---|---|
loading | boolean | true | While true the shimmer shows; set it false to hand off to children. |
children | ReactNode | The real content, laid out invisibly and inert while loading. Without children the skeleton is a plain block. | |
text | boolean | false | Cover the middle 60% of each line box, so it reads as a line of text. |
block | boolean | false | Lay the wrapper out as a block instead of inline, for cards and rows. |
className | string | Size and radius classes. Default radius rounded-control-xs; pass rounded-pill for avatars. |
SkeletonText
| Prop | Type | Default | Description |
|---|---|---|---|
lines | number | 3 | Number of lines; the last one is shorter. |
loading | boolean | true | |
className | string | "" |
Accessibility
- A skeleton wrapping content sets
aria-busywhile loading, and the stand-in content isinert, so it cannot be focused, clicked or read until it arrives. - The shimmer itself is hidden from assistive tech. Announce the loaded state yourself if it matters, for example in a live region.
Motion
Every skeleton paints the same viewport-space highlight and every shimmer is pinned to the same start time, so a single band sweeps across the whole page every 2s instead of each block flashing on its own beat. When loading ends the shimmer fades out as the content fades in from a 4px blur in the same box. Reduced motion: a still tint, and an opacity handoff in 100ms.
The shared sweep has limits. The band is painted with background-attachment: fixed, which iOS Safari ignores, so there each skeleton sweeps its own box (still on the shared beat). Inside an ancestor that keeps a transform or will-change (an entrance animation that never resets), the background becomes relative to that element; end entrances with transitionEnd: { transform: "none" }. The loop does not pause off-screen: skeletons are short-lived.
Notes for AI
Prefer wrapping the real component in Skeleton over drawing separate placeholder shapes: pass stand-in content of a typical length while data is missing (user?.name ?? "Maya Okafor"), and the placeholder will match the loaded layout exactly. Use text for text, a rounded-* class for avatars and media, and block when the wrapper should fill its row.
Do not swap between a skeleton tree and the loaded tree with a conditional: keep the same Skeleton mounted and flip loading, so the handoff animates in place. Do not add your own shimmer or pulse.
Related components
- Loading Spinner: a wait with no layout to stand in for.
- Animated Progress Bar: a task with measurable progress.
- Avatar and Avatar Group: a picture to wrap while the person loads.