Skeleton

CSS loading placeholders that reserve content geometry.

When to use

Use a skeleton while content is loading and its expected geometry is known. Match the eventual layout so replacing the placeholders does not move surrounding content. Use Progress for measurable work.

Loading region

A skeleton reserves expected content geometry; a skeleton screen represents a larger region. Use progress for measurable completion.

Set aria-busy="true" on the stable region and aria-hidden="true" on placeholders. Add one status only when needed. Never apply skeleton classes to real controls; CSS cannot remove them from keyboard order.

Loading profile…

HTML
<section aria-busy="true" aria-describedby="profile-loading-status">
	<p id="profile-loading-status" role="status">Loading profile…</p>
	<div aria-hidden="true">
		<span class="skeleton skeleton-avatar"></span>
		<div class="skeleton-lines">
			<span class="skeleton skeleton-headline skeleton-sm"></span>
			<span class="skeleton skeleton-text w-50"></span>
		</div>
	</div>
</section>

Variants

Combine .skeleton with a shape and optional .skeleton-sm, .skeleton-md or .skeleton-lg size.

HTML
<span class="skeleton skeleton-headline" aria-hidden="true"></span>
<span class="skeleton skeleton-text" aria-hidden="true"></span>
<span class="skeleton skeleton-avatar" aria-hidden="true"></span>
<span class="skeleton skeleton-image" aria-hidden="true"></span>
<span class="skeleton skeleton-pill" aria-hidden="true"></span>
<span class="skeleton skeleton-square" aria-hidden="true"></span>

Multi-line text

Wrap .skeleton-text items in .skeleton-lines. Children set the count; variables control gap and final width.

HTML
<div class="skeleton-lines w-75" aria-hidden="true">
	<span class="skeleton skeleton-text"></span>
	<span class="skeleton skeleton-text"></span>
	<span class="skeleton skeleton-text"></span>
	<span class="skeleton skeleton-text"></span>
</div>

Dimensions, ratios and shapes

Use width utilities, .skeleton-aspect-square, .skeleton-aspect-video and radius utilities. Set component variables for exact dimensions.

HTML
<span class="skeleton skeleton-text w-50" aria-hidden="true"></span>
<span class="skeleton skeleton-square skeleton-lg rounded-circle" aria-hidden="true"></span>
<span class="skeleton skeleton-aspect-video w-25" aria-hidden="true"></span>
<span
	class="skeleton"
	style="--skeleton-width: 8rem; --skeleton-height: 4rem; --skeleton-border-radius: 1rem;"
	aria-hidden="true"></span>

Match final content dimensions to prevent layout shift.

Skeleton screen compositions

Cards and responsive grids

Lists

Tables

Forms

Compositions support both themes, forced colors and reduced motion without changing geometry.

Replacing the loading state

Replace the composition atomically with one loaded, empty or error state. Keep the region mounted, set aria-busy="false" and preserve focus when possible. Never layer skeletons over real controls. Use Empty State for no content and Alert for failure.

Use at most one non-duplicated status per region.

Accessibility and behavior

  • Keep the content region mounted and mark it aria-busy="true" while loading. Hide placeholder shapes from assistive technology and use at most one meaningful status message.
  • Use decorative elements for placeholders. Hiding a container from assistive technology does not remove real controls from keyboard navigation.
  • On completion, replace placeholders with the loaded, empty or error state, clear busy state and preserve focus. Motion preferences should not change the reserved geometry.

CSS variables

Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.

TokenDefaultPurposeScope / state
--skeleton-width100%Placeholder width; shape and size modifiers may replace it..skeleton
--skeleton-height1remPlaceholder height; text variants derive it from font size and line height..skeleton
--skeleton-size2.5remWidth and height scale for avatar and square placeholders..skeleton
--skeleton-font-sizevar(--font-size)Font size used to calculate text placeholder height..skeleton
--skeleton-line-heightvar(--line-height-tight)Line height multiplier for text placeholder height..skeleton
--skeleton-control-height2.5remHeight of a pill placeholder..skeleton
--skeleton-aspect-ratioautoAspect ratio for image and square placeholders..skeleton
--skeleton-border-radiusvar(--border-radius-sm)Corner radius..skeleton
--skeleton-base-colorcolor-mix(in srgb, var(--text-color) 14%, var(--bg-surface))Static placeholder background..skeleton
--skeleton-highlight-colorcolor-mix(in srgb, var(--text-color) 5%, var(--bg-surface))Moving shimmer color..skeleton
--skeleton-animation-duration1.6sDuration of one animation cycle..skeleton
--skeleton-animation-easingease-in-outTiming curve of the animation..skeleton
--skeleton-line-gapvar(--spacer-2)Space between stacked text placeholders..skeleton-lines
--skeleton-last-line-width65%Width of the final text placeholder in a line group..skeleton-lines