Feature Library

Loading, empty and error states

0.05 CPU ms
A still of the Loading, empty and error states demo
Still
The live demo starts when it’s in view.Pick a network speed in the controls · search, filter to starred, switch list, cards and table · watch the strip

The states every view needs, done calmly: a tiny state machine (idle → loading → slow → ready | empty | error) with a grace delay so fast loads never flash a…

What it costs a frame

0.05 ms
GPU
not used
CPU, median
0.05 ms
CPU, 95th pct
0.09 ms
Draw calls
0
Weight
Light

Measured 7 November 2026 on 13th Gen Intel(R) Core(TM) i9-13900H, Chrome 156, 1920×1080 at 1×. 600 frames × 3 rounds, median kept. What ran: Measured with the demo reloading itself cold every 2.6 s on the 2 s network and cycling list, cards and table, so most frames show a sweeping skeleton and every few seconds one is swapped for content. The per-frame script is only the teaching timeline; the sweep is one CSS animation and costs no script at all. Phones: tiers are being measured next.

On every machine it was measured on
MachineGPU msCPU msCPU p95
unknown GPU · 13th Gen Intel(R) Core(TM) i9-13900Hreference · measuring toolnot timed0.050.09
apple · Apple A19 Proin a browser tab · 16 November 2026not timed0.040.10
Intel Arc 140V (Xe2-LPG) · Intel Core Ultra 7 258Vin a browser tab · 15 November 2026not timed0.060.14

Bars against one 16.7 ms frame. A browser-tab run is timed in a visible tab without the tool’s scripted input, so read it as close, not exact.

What it needs

Renders with
DOM and CSSPlain DOM and CSS: every current browser.
Your browser
Runs hereNo WebGPU needed
Depends on
NothingNo other packages

What it’s for

  1. Lists, grids and tables that fetch
  2. Search as you type
  3. Dashboards and panels that refresh
  4. Imports and uploads with progress
  5. First-run screens
  6. Offline and server errors

Pitfalls, in brief

  1. By default the slow note and a failed refresh’s line are put in a slot above the content, which takes room only while it shows: the content moves down when a refresh fails and back up when it recovers.
  2. Import loading-states.base.css, then loading-states.css (or your own look instead): the base gives the bones their shape (a line is one line of text tall) and the presets their layout, so without it a skeleton collapses to nothing.
  3. Pass ctx.signal to fetch.
  4. A skeleton only prevents a jump if it matches: build it with your real row, card and table classes and the same font size (a line bone is one line box tall, 1lh, in its own font).
  5. The minimum on screen can hold a result back by up to minShow ms after it arrived; keep it near 500 ms.
5 more in brief
  1. isEmpty is about the server’s answer.
  2. Do not put the live region inside the aria-busy element: some screen readers hold back what a busy region says. stateRegion puts it beside the body for that reason.
  3. background-attachment: fixed is ignored on iOS Safari, so there each bone runs its own sweep; still a sweep, just not one shared band.
  4. A refresh that fails keeps the old content with a banner (phase error, data kept).
  5. Reduced motion stops both the sweep and the pulse and makes the indeterminate bar still: the skeleton and the words still say it is loading.
10 pitfalls in full, the hook-up guide, the module source and its tests come with the part.

Where it comes from

Written for the library. Fully custom code.

WAI-ARIA 1.2 (W3C): aria-busy on the region while it loads, the progressbar role and its values, and a polite live region for what arrives. Written here from scratch.

Skeleton screens (Luke Wroblewski, 2013): The idea of placeholders in the shape of the coming content instead of a spinner. No code.

Delayed, minimum-duration busy indicators (React’s Suspense design): The idea of a delay before a busy indicator appears and a minimum once it has (busyDelayMs and busyMinDurationMs in its 2019 experiments). The machine here is written from scratch.

loadingskeletonshimmerempty stateerror stateretryprogress barstate machinearia-busylive regionabortaccessibilitydomcssno dependencies

Near it in the frame