Skip to content
flyingsalmon

Skeleton

A pulsing placeholder that holds the shape of content that has not arrived yet.

Installation

npx shadcn@latest add @flyingsalmon/skeleton

Usage

import { Skeleton } from '@/components/ui/skeleton'

export function SkeletonUsage() {
  return (
    <div aria-busy="true">
      <Skeleton />
      <Skeleton className="w-3/4" />
    </div>
  )
}

Examples

Variants

Text is the default: one line tall and full width. Circle and rectangle carry no size of their own, so you give them one.

Text follows the font

A text block is one line tall in the surrounding font, so stacked lines scale with the type they stand in for.

Small text line

Heading line

A loading region

Toggle the content. The skeleton matches the shape of the real content, and the container carries aria-busy while it waits. The content replaces it at once.

Guidelines

When to use

  • For a region whose shape is known and whose content has not arrived: a list, a card, a page on first load.

When not to use

  • Use Spinner for an action that is running, such as a form submitting. The control shows its own busyness.
  • Use Progress for a long job with a known end, where the traveller wants to see how far along it is.
  • Use Empty state when the region is legitimately empty. A skeleton says content is coming, and none is.

Do and don’t

  • Do
    Draw the real layout: the same cards, borders, grid, and number of sections, with lines that vary in width like text.A placeholder that matches the real content lets it arrive without the page jumping.
  • Do
    Use a rectangle for an image or a bar, and text lines for words.Each placeholder hints at what will fill it, so the traveller reads the page before it arrives.
  • Don’t
    Swap a control the traveller just pressed for a skeleton.The control should stay and show its own busyness. A skeleton in its place makes the action vanish. A wait gets a spinner or a skeleton, never both.

Accessibility

The skeleton is always aria-hidden and never takes a tab stop, so a screen reader hears nothing from it. The region that is loading owns the announcement: put aria-busy on the container that will hold the real content, and an aria-label such as “Loading trips” that names what is coming, not on each block.

API

Skeleton

Also takes every <div> attribute except children and aria-hidden. Size it with className.

PropTypeDefaultDescription
variantSkeletonVariantSkeletonVariant.TextText, Circle, or Rectangle.

  • Spinner

    The mark for an action that is running.
  • Progress

    A bar for work with a known end.
  • Empty state

    What a region says when it is legitimately empty.
  • Error state

    What a region says when its content failed to arrive.