Skip to content

Design system

Documentation

DesignComponents / Skeleton

Components / Skeleton

Beta

Skeleton

Show the shape of content while its first load is pending.

On this page

Examples

Text, avatar, and media placeholders

Match the placeholder geometry to the content that will appear. Skeleton is decorative and must not stand in for an error or empty message.

Text, circular avatar, and rectangle placeholders

Try the props

Choose one supported placeholder shape and a text line count.

Skeleton property playground

When to use

Use Skeleton for the initial wait when the shape of the eventual content is known. Keep the placeholder layout close to the content it replaces. Use Spinner for a local operation and EmptyState when the request has completed but there is nothing to show.

Usage

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

<Skeleton shape="text" lines={3} />

Skeleton is decorative, uses aria-hidden, and does not communicate loading completion or errors.

API

Component API
PropTypeDefaultDescriptionConstraints
shape"text" | "rectangle" | "circle""text"Placeholder geometry.Compose multiple shapes to reflect the real content layout.
linesnumber1Number of text placeholder lines.Clamped to 1–12 and only applied to text shape.
classNamestring—Additional styling for the root or single placeholder.Use semantic spacing and size tokens.

Tokens

Component tokens
TokenRoleEffective valueUsage
--color-bg-subtle / mutedPlaceholder fillShared neutral surfaceKeeps placeholders low emphasis in both themes.
--radius-sm / --radius-lgPlaceholder shapeText / mediaMatches nearby text and Card surfaces.
Reduced motionMotion preferenceStatic placeholderPulse animation stops when reduced motion is requested.

Accessibility

  • Skeletons are hidden from assistive technology so repeated placeholder blocks are not announced as content.
  • Keep a separate status or heading when users need to know what is loading.

Do and don’t

Do

Match the count and rough size of the content that will replace the placeholder.

Don’t

Use a skeleton to represent an error, an empty result, or indefinite background work.

  • Spinner communicates work in progress.
  • EmptyState communicates that no content is available.