Skeleton

The canonical loading-placeholder primitive. <Skeleton /> claims layout space for content that isn't ready yet, and animates lightly so users can tell the page is alive without demanding their attention.

Three exports ship on a single shared recipe:

• <Skeleton /> — the block primitive; any width × height × radius.
• <SkeletonText /> — multi-line text placeholder; auto-shortens the last line.
• <SkeletonAvatar /> — circular placeholder sized 1:1 with <Avatar />.

Why this exists

Pages that re-flow when data arrives feel broken. Skeletons solve two jobs:

1. Reserve space. The layout doesn't jump when content lands — width / height on the placeholder match the eventual content's box.
2. Signal liveness. A subtle shimmer or pulse tells the user "we're still loading" without spinning at them. Both animations halt under prefers-reduced-motion.

Anatomy

┌──────────────────────────────────────────────────────┐
│  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  │  ← <Skeleton>
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  │
│  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  │  ← <SkeletonText>
│  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ (shortened)         │
└──────────────────────────────────────────────────────┘

        ●  ← <SkeletonAvatar>  (rounded-full, size matches <Avatar>)

┌──────────────────────────────────────────────────────┐
│  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  │  ← <Skeleton>
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  │
│  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  │  ← <SkeletonText>
│  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ (shortened)         │
└──────────────────────────────────────────────────────┘

        ●  ← <SkeletonAvatar>  (rounded-full, size matches <Avatar>)

Variants

Animations

All three respect prefers-reduced-motion: the animation halts and a 70% opacity fallback paints in its place. ARIA semantics are unchanged.

Examples

Props

<Skeleton />

<SkeletonText />

Extends <Skeleton /> (minus width) with:

<SkeletonAvatar />

Extends <Skeleton /> (minus width / height / rounded) with:

Accessibility

• Root announces once. <Skeleton /> and <SkeletonText /> carry role="status" and aria-label="Loading" so screen readers report the loading state. Override aria-label to localize or to disambiguate ("Loading user profile", "Loading messages", …).
• Nested lines are silent. Each <Skeleton /> line inside <SkeletonText /> is aria-hidden="true" — only the wrapper announces. The same escape hatch is available on a bare <Skeleton aria-hidden="true" /> when you want to nest one inside a custom wrapper that owns the announcement.
• Reduced motion. prefers-reduced-motion: reduce halts the shimmer / pulse animation via the motion-reduce: Tailwind variant and drops opacity to 70% so the placeholder is still visually distinct from the surface.
• axe-core. Zero violations across the variant × color × animation matrix.
• Replace, don't overlay. When real data lands, swap the <Skeleton /> for the actual content — screen readers want the announcement transition (status → content). Don't paint the content under the skeleton.

Theming

defineTheme({
  components: {
    Skeleton: {
      defaultProps: { animation: 'pulse', rounded: 'sm' },
      styleOverrides: {
        root: 'bg-bg-paper', // tighter contrast against page background
      },
    },
  },
});

defineTheme({
  components: {
    Skeleton: {
      defaultProps: { animation: 'pulse', rounded: 'sm' },
      styleOverrides: {
        root: 'bg-bg-paper', // tighter contrast against page background
      },
    },
  },
});

You can also retune the shimmer palette per theme by setting the two CSS variables the shimmer gradient references — set them anywhere from :root down to an element-level style:

:root {
  --sds-skeleton-base: rgba(0, 0, 0, 0.06);
  --sds-skeleton-highlight: rgba(255, 255, 255, 0.18);
}

:root[data-mode='dark'] {
  --sds-skeleton-base: rgba(255, 255, 255, 0.06);
  --sds-skeleton-highlight: rgba(255, 255, 255, 0.16);
}

:root {
  --sds-skeleton-base: rgba(0, 0, 0, 0.06);
  --sds-skeleton-highlight: rgba(255, 255, 255, 0.18);
}

:root[data-mode='dark'] {
  --sds-skeleton-base: rgba(255, 255, 255, 0.06);
  --sds-skeleton-highlight: rgba(255, 255, 255, 0.16);
}

Both have sensible RGB fallbacks baked into the gradient string, so the shimmer works out of the box on every theme — these overrides are pure refinement.