Skeleton

A skeleton is a placeholder for content that is loading. By rendering a neutral block where real content will eventually appear, you give the user an early sense of layout and reduce both perceived loading time and Cumulative Layout Shift (CLS).

When to use

• Async-loaded content where the eventual shape is predictable (lists, cards, tables, avatars).
• On initial page load, before data has resolved.

For a whole list page, the List Page Loading States recipe shows where the skeleton belongs and what renders around it.

When not to use

• For very short fetches (under ~200 ms) — a flash of skeleton is more distracting than helpful.
• To convey error or empty states. Use Empty instead.
• As a permanent decorative shape.

Sizing

Default height is 1rem. Override className with h-*, w-*, and rounded-* utilities to match the real content's dimensions — the more closely the skeleton matches, the less layout shift on swap.

Accessibility

Skeletons are decorative and convey no semantic meaning to assistive tech, so Skeleton renders aria-hidden="true" by default. Pass aria-hidden={false} to opt out. If the underlying region is loading, also announce it to screen readers, for example wrap it in an element with role="status" and a visually-hidden "Loading…" label.

1import { Skeleton } from "@ngrok/mantle/skeleton";2 3<div role="status" aria-live="polite">⋯4	<span className="sr-only">Loading profile…</span>5	<Skeleton className="h-12 w-12 rounded-full" />6</div>;

1import { Skeleton } from "@ngrok/mantle/skeleton";2 3<Skeleton className="w-full" />;

Examples

Composition: Skeleton within a Media Object

Include the Skeleton within other components. Pass Tailwind utility classes for further control.

1import { MediaObject } from "@ngrok/mantle/media-object";2import { Skeleton } from "@ngrok/mantle/skeleton";3 4<MediaObject.Root className="w-full max-w-96 items-center">⋯5	<MediaObject.Media>⋯6		<Skeleton className="h-12 w-12 rounded-full" />7	</MediaObject.Media>8	<MediaObject.Content className="space-y-3">⋯9		<Skeleton className="w-full" />10		<Skeleton className="w-4/5" />11	</MediaObject.Content>12</MediaObject.Root>;

Polymorphism

Skeleton accepts an asChild prop. When true, it renders its single child instead of its default <div>, forwarding its class names, data-* attributes, and ref onto that child. Reach for this when the placeholder should also be a more semantic element.

1import { Skeleton } from "@ngrok/mantle/skeleton";2 3<Skeleton asChild className="h-12 w-12 rounded-full">⋯4	<span />5</Skeleton>;

API Reference

Skeleton

The Skeleton accepts the following props in addition to the standard HTML div attributes.