Loader
A Loader communicates that something is happening when the duration or progress fraction isn't known — a network fetch, a bulk write, anything without a meaningful 0–100 value. For processes where the total is known, use ProgressBar instead.
Overview
When to use
- Waiting on a network request or write where progress can't be measured.
- Any spot that currently renders nothing (
null) while data loads — a blank window reads as broken, not busy.
When not to use
- When the process has a real, known progress value — use
ProgressBar. - For a brief (under 100ms) synchronous update — showing and immediately hiding a loader reads as a flicker, not feedback.
With Label
The bar renders alone by default. Pass label for visible context — it also becomes the accessible name announced to screen readers.
Applying changes…
Accessibility
The root element sets role="status" and aria-live="polite", so assistive tech announces the label without stealing focus. When no label is given, an aria-label="Loading" fallback keeps the region from being silent.
<Loader label="Applying changes…" />
Controls
Interactive controls are available in Storybook. Open Storybook
Props
Token mapping
| Property | Token |
|---|---|
| track background | --color-bg-page |
| marquee fill | --color-accent-success |
| bevel (top-left outer) | --sunken-outer-dark |
| bevel (bottom-right outer) | --sunken-outer-light |
| bevel (top-left inner) | --sunken-inner-dark |
| bevel (bottom-right inner) | --sunken-inner-light |
| label text | --color-text-primary |
Do's and don'ts
| Do | Don't |
|---|---|
Replace a blank/null render with a Loader during any async wait longer than a beat. | Stack multiple Loaders on one screen — one busy indicator per operation is enough. |
Pass a label describing what's happening ("Applying changes…") rather than a generic "Loading". | Use Loader for a process with a real percentage — that's what ProgressBar is for. |
Changelog
| Date | Change |
|---|---|
| 2026-08-24 | Initial component — built for the Gym app's in-app training-sync feature, and to replace several existing blank-screen loading gaps |