Skeleton

Shape Variants

Animation Variants

The shimmer variant is more visually engaging but slightly more expensive to render. For pages with dozens of skeleton elements, the pulse variant may perform better. Preview both in the Animation & Easing Tool.

Composition Patterns

Rather than individual skeleton shapes, most implementations compose skeletons into templates that mirror real component layouts:

• Card Skeleton: Rectangle (image) + heading skeleton + 2 text skeletons + circle (avatar)
• List Item Skeleton: Circle (avatar) + heading + text
• Table Skeleton: Grid of rectangles matching column widths
• Article Skeleton: Large rectangle (hero) + heading + paragraph block
• Profile Skeleton: Large circle (avatar) + heading + text + text

These composed templates are matched 1:1 to the real component, so the transition from skeleton to content is seamless.

Skeleton Properties

Compound Component API

Some implementations (react-loading-skeleton, Chakra) offer a wrapper API:

<Skeleton isLoading={isLoading} fallback={<SkeletonCard />}>
  <ActualCard data={data} />
</Skeleton>

This pattern cleanly separates loading and loaded states without conditional rendering in the parent.

Design Token Mappings

Skeletons use a narrow set of tokens — primarily color and animation. See the Design Tokens Complete Guide for token architecture.

Dark Mode Considerations

Skeleton colors must invert for dark mode. The base should be slightly lighter than the page background, and the highlight slightly lighter still — just enough to be visible without being harsh:

/* Light mode */
--skeleton-base: var(--color-neutral-200);   /* #e5e7eb */
--skeleton-highlight: var(--color-neutral-100); /* #f3f4f6 */

/* Dark mode */
--skeleton-base: var(--color-neutral-800);   /* #1f2937 */
--skeleton-highlight: var(--color-neutral-700); /* #374151 */

Generate both light and dark skeleton palettes with the Color Palette Generator.

Skeleton States

Like Spinners, skeletons don't have interactive states (hover, focus, active). Their lifecycle is about visibility and transition:

Transition Best Practices

The transition from skeleton to content is the most important moment. Poor transitions (content popping in abruptly, layout shifts) can negate the perceived-performance benefits:

1. Match dimensions exactly. The skeleton must be the same size as the real content. Any layout shift is jarring.
2. Crossfade, don't swap. Fade the skeleton out (opacity 1→0) while fading content in (opacity 0→1). Duration: 200–300ms.
3. Stagger content appearance. Load and reveal above-the-fold content first, then progressively reveal lower sections. This prevents a "flash of everything."
4. Never show skeleton after content. If data loads faster than expected, skip the skeleton entirely (use a delay similar to the Spinner approach).

Accessibility — Skeleton

Skeletons are purely decorative placeholders — they have no interactive role and should be invisible to screen readers. The accessibility work is in communicating the loading state properly. Test skeleton-to-content contrast with the Contrast Checker.

ARIA Pattern

<!-- Region with skeleton loading -->
<div aria-busy="true" aria-label="Loading feed">
  <!-- Skeleton elements — hidden from AT -->
  <div class="skeleton skeleton-card" aria-hidden="true"></div>
  <div class="skeleton skeleton-card" aria-hidden="true"></div>
  <div class="skeleton skeleton-card" aria-hidden="true"></div>

  <!-- Screen reader announcement -->
  <div role="status" class="sr-only">Loading content…</div>
</div>

<!-- After loading completes -->
<div aria-busy="false">
  <article><!-- real content --></article>
  <article><!-- real content --></article>
</div>

Key points:

• Mark all skeleton elements as aria-hidden="true" — they are decorative
• Set aria-busy="true" on the container that will receive content
• Provide a role="status" announcement so screen readers know loading is happening
• When loading completes, set aria-busy="false" and remove the status message

WCAG Success Criteria

Layout Stability (CLS)

Skeletons directly impact Core Web Vitals' Cumulative Layout Shift (CLS). The skeleton must reserve the exact space that content will occupy. If your skeleton is 200px tall but the real content is 350px, you'll get a layout shift when content loads — defeating the purpose. Measure your CLS with Chrome DevTools or Lighthouse and ensure skeleton-to-content transitions produce zero shift.

Do

• Match the skeleton to the real content layout precisely. Width, height, spacing, element count — all must mirror the actual UI. This is the fundamental rule.
• Use varying widths for text skeletons. Don't make every line the same width. Use 100%, 85%, 60% to mimic natural text line lengths.
• Keep skeletons simple. Gray shapes. No icons, no brand colors, no detail. The point is a silhouette, not a preview.
• Apply shimmer/pulse animation for visual feedback that loading is active. Static skeletons can be mistaken for broken UI.
• Combine with lazy loading. Show skeletons for below-the-fold content and load it as the user scrolls.
• Set a minimum display time (300ms) to prevent the skeleton from flashing for fast loads.
• Crossfade from skeleton to content. Don't let content "pop" in abruptly.

Don't

• Don't show skeletons forever. If loading fails, transition to an error state. Set a maximum display time (15–30 seconds) before showing an error or retry option.
• Don't use skeletons for unknown layouts. If you can't predict the content shape, use a Spinner.
• Don't over-detail skeletons. Showing exact icon shapes, text lengths, or brand elements makes the transition feel like content changing rather than content loading.
• Don't animate skeletons aggressively. Rapid or flashy shimmer is distracting and can fail WCAG 2.3.1.
• Don't show skeleton + spinner together. Pick one approach. Skeleton screens replace spinners; they don't complement them.
• Don't forget dark mode. Skeleton colors that work on white backgrounds disappear on dark backgrounds. Use semantic tokens.
• Don't cause layout shifts. The skeleton must be pixel-perfect in dimensions relative to the content it represents. Measure with CLS tools.

Content Loading Strategies

Explore loading patterns and prebuilt skeleton animations in the Loader Generator.

Design System Implementations

Material Design 3 doesn't have a dedicated "skeleton" component in its spec — instead, it recommends using a container with a Placeholder layer that uses a subtle pulse animation (opacity oscillation between 0.04 and 0.12 on neutral tones). Material's approach is more restrained than the shimmer pattern — just a gentle breathing effect. This aligns with Material's philosophy of calm, non-distracting loading states.

Ant Design's Skeleton component is one of the most fully-featured implementations. It offers Skeleton.Avatar, Skeleton.Title, Skeleton.Paragraph, and Skeleton.Button sub-components that compose into realistic loading templates. The active prop enables shimmer animation, and the loading prop wraps real content — when loading becomes false, the skeleton seamlessly transitions to children. It also supports round shapes and custom paragraph row counts/widths.

react-loading-skeleton (an independent library, not a design system) is the de facto standard for React skeleton loading. It uses CSS @keyframes with background-position for the shimmer, provides <Skeleton count={5} /> for multi-line blocks, supports circle for avatars, and automatically adapts to parent width. Its SkeletonTheme provider allows global color customization.

Chakra UI provides a Skeleton component with startColor and endColor props for the animation gradient. It also offers SkeletonText (renders multiple lines with the last line shorter) and SkeletonCircle. The isLoaded prop triggers a smooth crossfade from skeleton to content — one of the cleanest transition implementations.

Shadcn/ui offers a bare-minimum Skeleton — just a <div> with animate-pulse (Tailwind's built-in pulse animation) and a muted background. No shimmer, no sub-components, no isLoading wrapper. You compose templates manually.

Bootstrap doesn't include skeletons in its core library. The community typically implements them using Bootstrap's existing utility classes or third-party plugins.

For creating shimmer and pulse animations with precise timing, use the Animation & Easing Tool. Generate skeleton color pairs (base + highlight) for both light and dark themes with the Color Palette Generator. Browse prebuilt skeleton patterns in the Loader Generator.