Basel Standard / Docs

Skeleton

Layout-preserving loading placeholder for content that has not arrived yet.

Skeletons hold the structure of the final interface while data is still loading. They are useful when the user already understands what kind of surface is coming next and only needs the page rhythm to stay stable. In this system the variants are quiet and structural rather than glossy or animated for effect.

Installation

Install

Purchase access, then open /account/install to issue a registry token.

Usage

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

<div className="grid gap-3">
  <Skeleton variant="line" className="w-24" />
  <Skeleton variant="card" className="h-12 w-full" />
</div>

Why This Primitive Exists

Loading states should preserve trust, not create visual noise. A skeleton keeps the layout believable while content is on the way and reduces sudden reflow when the final data appears.

Use it when the shape of the incoming content is known.
Prefer it over a spinner when the page layout itself should remain legible during loading.
Avoid showing a skeleton for long unknown waits when a clearer status message would explain more.

Examples

Basic Content Stack

The simplest pattern mirrors the major lines and blocks of the finished surface.

<Skeleton variant="line" className="w-24" />
<Skeleton variant="table" className="h-8 w-full" />

Variant Coverage

The repo includes several variants so loading states can match the surface they are standing in for without rewriting local styling.

line

block

card

editorial

<Skeleton variant="block" className="h-20 w-full" />
<Skeleton variant="editorial" className="h-24 w-full" />

In Context

A good loading state stays close to the final geometry. That is more useful than a stack of identical gray boxes with no relation to the page that will eventually render.

Loading state

Skeletons preserve layout rhythm while content is still arriving.

Keep the geometry close to the final content so the page remains legible and stable during fetches.

<div className="grid gap-3 border border-border p-4">
  <Skeleton variant="line" className="w-20" />
  <Skeleton variant="table" className="h-8 w-full" />
</div>

Guidance

Mirror Real Geometry

Match the approximate width and height of the final content.
Preserve key hierarchy such as headings, cards, rows, and captions.
Avoid placeholder layouts that look nothing like the finished surface.

Choose The Variant By Surface

Use line for headings, labels, and short metadata.
Use table for dense row-based loading states.
Use editorial or card when the loading state belongs to a more art-directed surface.

Keep Loading Honest

Use skeletons for short to moderate waits where the final structure is already clear.
If the data is missing, blocked, or failed, switch to explicit empty or error states instead.
Do not combine several decorative effects just to make waiting look more dramatic.

API Reference

`Skeleton`

Skeleton renders a div and accepts React.ComponentProps<"div"> plus the repo variant set.

Prop	Type	Default	Notes
`variant`	`"default" \| "line" \| "block" \| "card" \| "editorial" \| "table"`	`"default"`	Selects the background treatment that matches the target surface.
`className`	`string`	`undefined`	Use this for width, height, and layout positioning.

Variant Notes

Variant	Use it for
`default`	Generic placeholder blocks when no surface-specific treatment is needed.
`line`	Short text lines, labels, and headings.
`block`	Neutral content regions.
`card`	Card-like panels or grouped content blocks.
`editorial`	More art-directed editorial or landing-style surfaces.
`table`	Dense row placeholders on tabular layouts.

The component also accepts ordinary div attributes like style, aria-hidden, and custom data attributes.

Previous: Sidebar Next: Slider