Skeleton

The shape of something that has not loaded yet. It reserves the space the real thing will take, so a card does not grow by 200px under the reader when its image arrives.

import { Skeleton } from 'neba';

<Skeleton shape="circle" size="lg" />
<Skeleton shape="rect" height={120} />
<Skeleton lines={3} />

Props

Prop	Type	Default	Description
shape	'line' | 'rect' | 'circle'	'line'	What it stands in for: a run of text, a block (image, chart, card), or something round (an avatar)
lines	number	1	How many lines to draw, for shape="line". The last is drawn short, the way the last line of a paragraph is. Ignored by the other shapes
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	The scale of the thing being stood in for: the type scale for a line, the diameter for a circle, the default block height for a rect
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'secondary'	Colour family. Worth leaving alone: a placeholder carrying a semantic colour is saying something about content that has not arrived
width	number | string	—	An explicit width. Numbers are pixels
height	number | string	—	An explicit height. Numbers are pixels
animated	boolean	true	The travelling highlight. A reduced-motion preference already swaps it for a colour pulse, so this is not the accessibility switch
label	string	—	What a screen reader is told. Unset it is aria-hidden, because a dozen boxes each announcing themselves is worse than silence. Give it to the one that stands for a whole region and it becomes a status
render	useRender.RenderProp	—	Renders something other than a div (render={<span />}). Base UI's own escape hatch

Native <div> attributes pass through, and render swaps the element. The shared axes are described in prop conventions.

Examples

shape

The three shapes are the three things a layout is made of. line is a run of text, sized off the type scale, so a md line is as tall as md type. rect is a block (an image, a chart, a card), and falls back to a thumbnail height when no height is given. circle is drawn on the same ladder an Avatar uses, so the two are exactly the same size at the same size.

import { Skeleton } from 'neba';

export default function SkeletonShapes() {
  return (
    <div className="flex w-full max-w-96 flex-col gap-5">
      <div className="flex flex-col gap-2">
        <span className="text-[0.75rem] text-(--neba-muted-fg)">line</span>
        <Skeleton />
      </div>

      <div className="flex flex-col gap-2">
        <span className="text-[0.75rem] text-(--neba-muted-fg)">rect</span>
        <Skeleton shape="rect" />
      </div>

      <div className="flex flex-col gap-2">
        <span className="text-[0.75rem] text-(--neba-muted-fg)">circle</span>
        <Skeleton shape="circle" size="xl" />
      </div>
    </div>
  );
}

lines

lines draws a stack of bars with the leading of the type scale between them, and the last one short: the way the last line of a paragraph is. It applies to shape="line" and is ignored by the other two.

import { Skeleton } from 'neba';

export default function SkeletonLines() {
  return (
    <div className="flex w-full max-w-96 flex-col gap-6">
      <Skeleton size="sm" lines={2} />
      <Skeleton lines={4} />
      <Skeleton size="lg" lines={3} />
    </div>
  );
}

width and height

width and height take a number as pixels or a string as a CSS length. A line is full width unless told otherwise, which is what makes a heading placeholder a width away.

import { useState } from 'react';
import { Button, Card, Skeleton, Statistic } from 'neba';

export default function SkeletonSwapping() {
  const [loading, setLoading] = useState(true);

  return (
    <div className="flex w-full max-w-96 flex-col gap-3">
      <Card>
        {loading ? (
          <Skeleton shape="rect" height={64} label="Loading this month's usage" />
        ) : (
          <Statistic label="Requests this month" value={1284910} previousValue={1142380} />
        )}
      </Card>

      <Button size="sm" variant="outline" onClick={() => setLoading((value) => !value)}>
        {loading ? 'Finish loading' : 'Load again'}
      </Button>
    </div>
  );
}

animated

animated is the highlight travelling across the placeholder. Turn it off for a page holding dozens of them, or where the wait is long enough that motion becomes noise.

<Skeleton animated={false} lines={4} />

This is not the accessibility switch: a reduced-motion preference already replaces the sweep with a colour pulse without being asked.

Accessibility

• A skeleton is aria-hidden by default. A dozen placeholders each announcing themselves is worse than silence.
• Give label to the one skeleton that stands for a whole region and it becomes a status with aria-busy and that name. Do not label every bar in a stack.
• Prefer a skeleton over a spinner where the layout is known. It is the only loading indicator that keeps the page from reflowing when the content arrives.