Skeleton

Loading placeholders for text, cards, and avatars.

Overview

  • Reserve space for loading content. Provide a progress message when users need explicit status.

Aliases

placeholder, loading skeleton

When to use

  • Use Skeleton when the layout is known but the content has not loaded yet.
  • Match the placeholder shape to the surface that will appear so layout shift stays low.

When not to use

  • Avoid flashing a loading placeholder for a brief operation.
  • Do not use Skeleton when the system cannot predict the layout shape at all.

Structural parts

placeholder block

root

Carries placeholder size, shape, and shimmer treatment.

Public interface

Props
NameTypeDefaultDescription
variant'text' | 'card' | 'avatar''text'Chooses the placeholder shape family.
size'sm' | 'md' | 'lg''md'Sets the component size.
linesnumber1Number of lines to render for text placeholders.
themeThemeContract—Sets the theme used to resolve component styles.
Slots
NameDescription
defaultSkeleton is prop-driven and does not expose content slots.

Variants, sizes, and states

Variants

  • text: Line-based placeholder for body copy or metadata.
  • card: Block placeholder for grouped content surfaces.
  • avatar: Circular or rounded placeholder for identity surfaces.

Sizes

  • sm: Compact placeholder.
  • md: Default placeholder size.
  • lg: Larger placeholder for wider surfaces.

States

  • loading: Visible while content is pending.

Accessibility

Semantics

  • Skeleton is presentational. Provide a separate progress message when users need explicit status.

Keyboard

  • Skeleton is non-interactive.

Screen readers

  • Treat skeletons as decorative; pair them with a separate status message when loading needs to be announced.

Checklist

  • Verify that the control has an accessible name.
  • Verify that keyboard focus is visible in every state and size.
  • Identify disabled, selected, and error states with text or symbols as well as color.

Tokens and CSS variables

root

--dk-skeleton-bg
#e5e8ed
--dk-skeleton-shimmer
#f2f5fb
--dk-skeleton-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-skeleton-gap
clamp(0.563rem, 0.5156rem + 0.208vw, 0.703rem)
--dk-skeleton-block-size
0.875rem
--dk-skeleton-inline-size
100%

line

--dk-skeleton-line-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

Implementation notes

  • Provide a separate status message when loading needs an explanation.

Examples

Starter

Loading text

A few lines of loading body copy.

<Skeleton variant="text" size="sm" lines={3} />

Common patterns

Loading summary card

Reserve space while a card loads.

<Skeleton variant="card" size="md" />

Edge cases

Identity loading state

A placeholder for user or team identity surfaces.

<Skeleton variant="avatar" size="lg" />

Mathematical fixtures

Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.

text-md

pass

size=md|variant=text

  • Evidence: mathematical
  • Coverage: complete (1 / 1 declared kinds evaluated)
  • Declared: layout
  • Evaluated: layout
  • Layout: root · single-line 0 px single-line estimate; 0 px minimum width
    120 px: pass 240 px: pass 360 px: pass

block-md

pass

size=md|variant=block

  • Evidence: mathematical
  • Coverage: complete (1 / 1 declared kinds evaluated)
  • Declared: layout
  • Evaluated: layout
  • Layout: root · single-line 0 px single-line estimate; 0 px minimum width
    120 px: pass 240 px: pass 360 px: pass

avatar-lg

pass

size=lg|variant=avatar

  • Evidence: mathematical
  • Coverage: complete (1 / 1 declared kinds evaluated)
  • Declared: layout
  • Evaluated: layout
  • Layout: root · single-line 0 px single-line estimate; 0 px minimum width
    120 px: pass 240 px: pass 360 px: pass