Skeleton

Skeleton is the composer for animated (shimmer) placeholders. You describe the geometry of the areas that will become "skeletal" using the design system's SVG primitives (Rect, Circle) and Skeleton takes care of the animation and the theme colors.

Along with Skeleton, the package exports ready-made presets via the TextPreset components and the shortcuts ListPresetSkeleton, BulletListPresetSkeleton, CodePresetSkeleton and ItemPresetSkeleton.

When to use

✅ Use when…	🚫 Avoid when…
To indicate that a screen is loading data — `Skeleton` appears to load faster than a spinner or a blank screen. When the final component has a known structural shape (list, card, header, etc.) and the silhouette can be sketched while the data arrives.	When the shape of the final content is unpredictable. Use a spinner. For microtransitions (loads < 300 ms). Use a spinner or nothing. On entire screens without a clear hierarchy — it usually ends up visually more confusing than helpful.

Example — card with avatar

import { Circle } from '@apollion-dsi/core/scenario/circle-component';
import { Rect } from '@apollion-dsi/core/scenario/rect-component';
import { Skeleton } from '@apollion-dsi/core/skeleton/composed-skeleton';
 
<Skeleton width={300} height={100}>
  <Circle cx={50} cy={50} r={30} />
  <Rect x={100} y={35} width={200} height={13} />
  <Rect x={100} y={55} width={200} height={13} />
</Skeleton>;

We recommend composing with Apollion's SVG primitives (Rect, Circle). You can still use native SVG elements, but they do not pick up the theme colors.

A placeholder without the shimmer animation (a static color block) is only appropriate in a prototype — ship the animated Skeleton in production.

Colors

By default, Skeleton uses neutral.10 as the base color and neutral.30 as the shimmer color. You can override them via props:

default

primary tint

<Skeleton width={200} height={20} backgroundColor="primary.light" foregroundColor="primary.base">
  <Rect x={0} y={0} width={200} height={20} />
</Skeleton>

Presets

The 4 presets cover the common cases without you having to draw the geometry manually.

ListPresetSkeleton

BulletListPresetSkeleton

CodePresetSkeleton

ItemPresetSkeleton

import {
  ListPresetSkeleton,
  BulletListPresetSkeleton,
  CodePresetSkeleton,
  ItemPresetSkeleton,
} from '@apollion-dsi/core/skeleton/composed-skeleton';
 
<ListPresetSkeleton />
<BulletListPresetSkeleton />
<CodePresetSkeleton />
<ItemPresetSkeleton />

Properties


Prop	Type	Default	Description
`backgroundColor`	`AcceptColorType`	`'muted'`	The skeleton's base color — applied before the shimmer animation.
`children *`	`ReactNode`	—	The skeleton's SVG primitives (`Rect`, `Circle`) describing the shapes to render.
`foregroundColor`	`AcceptColorType`	`'edge.border'`	The shimmer color — the "wave" that sweeps over the base color.