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…
<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.
<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.
<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.
<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.
| Token | Default | Purpose | Scope / state |
|---|---|---|---|
--skeleton-width | 100% | Placeholder width; shape and size modifiers may replace it. | .skeleton |
--skeleton-height | 1rem | Placeholder height; text variants derive it from font size and line height. | .skeleton |
--skeleton-size | 2.5rem | Width and height scale for avatar and square placeholders. | .skeleton |
--skeleton-font-size | var(--font-size) | Font size used to calculate text placeholder height. | .skeleton |
--skeleton-line-height | var(--line-height-tight) | Line height multiplier for text placeholder height. | .skeleton |
--skeleton-control-height | 2.5rem | Height of a pill placeholder. | .skeleton |
--skeleton-aspect-ratio | auto | Aspect ratio for image and square placeholders. | .skeleton |
--skeleton-border-radius | var(--border-radius-sm) | Corner radius. | .skeleton |
--skeleton-base-color | color-mix(in srgb, var(--text-color) 14%, var(--bg-surface)) | Static placeholder background. | .skeleton |
--skeleton-highlight-color | color-mix(in srgb, var(--text-color) 5%, var(--bg-surface)) | Moving shimmer color. | .skeleton |
--skeleton-animation-duration | 1.6s | Duration of one animation cycle. | .skeleton |
--skeleton-animation-easing | ease-in-out | Timing curve of the animation. | .skeleton |
--skeleton-line-gap | var(--spacer-2) | Space between stacked text placeholders. | .skeleton-lines |
--skeleton-last-line-width | 65% | Width of the final text placeholder in a line group. | .skeleton-lines |