Loading Spinners
Variants — dots, typing, spinner, morph
With a visible label
Live status — steps reported by the backend
Connecting…In buttons — including successive steps via loadingStatus
Overlay pattern — busy region (built-in overlay + veil)
Overlay without veil + no-flash delay (the UploadDropArea pattern)
Press it: the spinner appears only after 150 ms, so a fast action never flashes one.
An inline loading indicator — pulsing dots (default), a rotating spinner
arc, bouncing typing dots (chat “waiting for a reply”), a morphing shape,
or a bar to place at the top of the content it covers. The bar is
indeterminate by default; give it a value (0–100) and it becomes a
determinate fill that completes, with progressbar semantics. Everything follows
the surrounding font size and text color (currentColor), so it works
standalone, inside buttons, or next to text.
For a full-surface “area rendering” loader — a tiling halftone dot field that covers a panel while a process runs — use LoadingGenerationArea.
The live status message works on every variant: on a determinate bar it
renders below the track and doubles as aria-valuetext when no detail is
set.
For buttons, prefer the Button’s own loading prop: it renders this spinner,
announces aria-busy and ignores presses while active. Feed the Button’s
loadingStatus to announce successive backend steps while it loads. Table
views announce a changing loadingLabel the same way (their loading text is
already a polite live region).
The progress-type loaders (bar with label and percentage, double bar for multi-file downloads, the completing circle with percentage, bar at the top of a card) are demoed on the Loading Progress page.
Import
Section titled “Import”<script> import Loading from "@invisible-ui/svelte/Loading.svelte";</script><script setup> import { Loading } from "@invisible-ui/vue";</script>import { Loading } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-loading></ds-loading>Live status — a running description
Section titled “Live status — a running description”For a process that reports its progress in steps, pass status: a message that
renders inside the polite role="status" region and is announced on every
change (the region is aria-atomic, so each new message is read in full). This
is how you surface a succession of backend-reported states — "Connecting…" →
"Fetching records…" → "Rendering…" — rather than a single static line.
<!-- `status` is whatever the backend last reported; each change is announced. --><Loading variant="spinner" status={currentStep} />It differs from label (a static accessible name) and from showLabel /
detail / the percentage (which are aria-hidden on purpose, so a fast-ticking
value isn’t re-announced on every frame). Use status for discrete, meaningful
steps; use detail for a value that changes continuously. status is ignored
on a determinate bar (a progressbar announces its value via aria-valuetext).
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "dots" | "spinner" | "bar" | "typing" | "morph" | "dots" | Indicator shape: pulsing dots or a rotating spinner arc. |
value | number | null | null | Completion percentage (0–100) for the bar variant: the bar becomes determinate (a fill that grows to done) and exposes progressbar semantics. Leave null for the indeterminate sliding segment. |
label | string | undefined | undefined | Accessible name announced by the status role. |
showLabel | boolean | false | Also render the label as visible text next to the indicator. |
showValue | boolean | false | Show the percentage (from value) as visible text. |
detail | string | undefined | undefined | Extra visible detail, e.g. "3 of 8 files" or "48 MB of 128 MB". |
decorative | boolean | false | Hide from assistive tech (the surrounding region announces the state). |
status | string | undefined | undefined | Live status message — a running description of what the process is doing ("Connecting…", "Fetching records…", "Rendering…"). Unlike label (a static accessible name), this renders as visible text **inside** the polite role="status" region and is announced on every change, so a succession of backend-reported steps is read out as it progresses. The region is aria-atomic, so each new message is announced in full. Ignored on a determinate bar (a progressbar announces its value, not free text) and when decorative. |
delay | number | 0 | No-flash delay (ms): keep the indicator hidden until this long has passed, so a fast operation never flashes a loader. If the component is removed before the delay elapses, nothing is ever shown. Follows the response-time rule — reveal a loader only once a wait is actually noticeable. Default 0 (shown immediately). |
overlay | boolean | false | Render as a centered overlay filling the nearest positioned ancestor — the built-in busy-region pattern. Mark that region aria-busy="true". |
veil | boolean | true | With overlay: paint a translucent backdrop that also blocks pointer interaction while busy. Set false to overlay just the indicator (no dim, no pointer blocking) — e.g. over a control whose own modal already guards interaction. |
| Prop | Type | Default | Description |
|---|---|---|---|
variant | LoadingVariant | "dots" | Indicator shape: pulsing dots, a rotating spinner arc, bouncing typing dots (chat "waiting for a reply"), a morphing shape (square ⇄ circle), or a bar (full-width track — place it at the top of the content it covers, e.g. a card). |
value | number | null | null | Completion percentage (0–100) for the bar variant: the bar becomes determinate (a fill that grows to done) and exposes progressbar semantics. Leave null for the indeterminate sliding segment. |
label | string | undefined | Accessible name. Defaults to the i18n catalog's "Loading…". |
showLabel | boolean | false | Also render the label as visible text next to the indicator. |
showValue | boolean | false | Show the percentage (from value) as visible text. |
detail | string | undefined | Extra visible detail, e.g. "3 of 8 files" or "48 MB of 128 MB". On a determinate bar it is also exposed as aria-valuetext. |
decorative | boolean | false | Hide from assistive tech (the surrounding region announces the state). |
status | string | undefined | Live status message — a running description of what the process is doing ("Connecting…", "Fetching records…", "Rendering…"). Unlike label (a static accessible name), this renders as visible text **inside** the polite role="status" region and is announced on every change, so a succession of backend-reported steps is read out as it progresses. The region is aria-atomic, so each new message is announced in full. On a determinate bar the text renders below the track and also feeds aria-valuetext when no detail is set (a progressbar announces its value text, not a live region). Ignored when decorative. |
delay | number | 0 | No-flash delay (ms): keep the indicator hidden until this long has passed, so a fast operation never flashes a loader. If the component is removed before the delay elapses, nothing is ever shown. Follows the response-time rule — reveal a loader only once a wait is actually noticeable. Default 0 (shown immediately). |
overlay | boolean | false | Render as a centered overlay filling the nearest positioned ancestor — the built-in busy-region pattern. Mark that region aria-busy="true". |
veil | boolean | true | With overlay: paint a translucent backdrop that also blocks pointer interaction while busy. Set false to overlay just the indicator (no dim, no pointer blocking) — e.g. over a control whose own modal already guards interaction. |
| Prop | Type | Default | Description |
|---|---|---|---|
variant | LoadingVariant | "dots" | Indicator shape: pulsing dots, a rotating spinner arc, bouncing typing dots (waiting for a chat reply), a morphing shape (square to circle), or a bar (a full-width track: place it at the top of the content it covers). For a whole surface that renders, use LoadingGenerationArea. |
value | number | null | null | Completion percentage (0 to 100) for the bar variant: the bar becomes determinate, a fill that grows to done, with progressbar semantics. Leave it null for the indeterminate sliding segment. |
label | string | — | Accessible name. Defaults to the catalog's "Loading…". |
showLabel | boolean | false | Also show the label as visible text next to the indicator. |
showValue | boolean | false | Show the percentage (from value) as visible text. |
detail | string | — | Extra visible detail, such as "3 of 8 files". On a determinate bar it is also the aria-valuetext. |
decorative | boolean | false | Hide from assistive technology (the surrounding region announces the state). |
status | string | — | Live status message: what the process is doing now ("Connecting…", "Fetching records…"). It shows as text inside the polite role="status" region and is announced in full on every change. On a determinate bar it shows below the track and is the aria-valuetext when no detail is set. Ignored when decorative. |
delay | number | 0 | No-flash delay in ms: the indicator stays hidden until this long has passed, so a fast operation never flashes a loader. Read once, when the component mounts. Default 0 (shown at once). |
overlay | boolean | false | Render as a centred overlay over the nearest positioned ancestor. Mark that region aria-busy="true". |
veil | boolean | true | With overlay: a translucent backdrop that also blocks the pointer while busy. Set false to overlay the indicator alone. |
| Attribute | Reactive | Description |
|---|---|---|
variant | yes | |
value | yes | |
label | yes | |
show-label | yes | |
show-value | yes | |
detail | yes | |
decorative | yes | |
status | yes | |
delay | yes | |
overlay | yes | |
veil | yes |
Reactive attributes re-render the element when they change after the first render.
Overlay pattern
Section titled “Overlay pattern”To mark a whole region as reloading, set overlay on the Loading and
aria-busy="true" on the region (which must be positioned, e.g.
position: relative). The indicator fills and centers over the region; by
default a translucent veil dims it and blocks pointer interaction while
busy. Set veil={false} to overlay just the indicator — no dimming, no pointer
blocking — for cases where a surrounding modal already guards interaction (this
is what UploadDropArea uses while the native file dialog opens). For richer progress
(bytes, file counts, percentages) use
Progress instead.
<div aria-busy={busy} style="position: relative"> …region content… {#if busy}<Loading overlay label="Reloading" />{/if}</div>When to show a loader — response-time UX
Section titled “When to show a loader — response-time UX”Whether to show a loader at all depends on how long the wait is (Nielsen’s response-time limits, and the Doherty threshold of ~400 ms):
| Wait | Perceived as | What to show |
|---|---|---|
| < 0.1 s | Instant | Nothing — a loader here only adds noise. |
| 0.1 – 1 s | Noticeable, still in flow | Usually nothing; avoid a layout that looks frozen. |
| 1 – 10 s | Attention wanders | An indeterminate indicator (dots / spinner) so the wait reads as “working”. |
| > 10 s | Flow broken | A determinate bar with a percentage/detail, and ideally a way to cancel. |
The delay rule — never flash a loader. Don’t show the indicator the instant an action starts. Reveal it only after a short delay (~100–200 ms): if the work finishes first, the user never sees a spinner. A loader that appears and vanishes within a frame reads as a glitch, not as progress. Once shown, keep it visible for a brief minimum (~300–500 ms) so it can’t blink out either.
This is built in — pass delay (ms) and Loading stays hidden until it elapses.
Mount it as soon as the work starts and remove it when the work ends; if that
happens before delay, nothing is ever shown:
{#if busy}<Loading variant="spinner" delay={150} />{/if}Elements exposes the same variants and progress semantics through attributes:
<ds-loading variant="bar" value="48" label="Importing files" show-value detail="3 of 8 files"></ds-loading>In React:
{busy ? <Loading variant="spinner" delay={150} /> : null}<Loading variant="bar" value={48} label="Importing files" showValue detail="3 of 8 files" />Set decorative only when the surrounding control or busy region already
announces the operation. Use status for discrete live updates and delay to
avoid flashing the indicator for fast operations.
The UploadDropArea uses exactly this: the native file dialog can take up to ~1 s to
open, so its spinner (delay={150}) appears only if the dialog is slow —
instant opens never flash one.
Accessibility
Section titled “Accessibility”- By default the indicator is a polite
role="status"with an accessible name (label; when omitted it comes from the i18n catalog, soLocaleProviderlocalizes it). A determinate bar is aprogressbarwitharia-value*, anddetaildoubles as itsaria-valuetext. - The visible text is
aria-hidden: the accessible name/value already carries it, and a ticking percentage inside a live region would be re-announced on every change. - Set
decorativewhen the surrounding region already announces the loading state (e.g. a button with its own label) — the dots are then hidden from assistive tech. - The pulse respects
prefers-reduced-motion: the dots stay visible, static.
Theming
Section titled “Theming”| Token | Purpose | Default |
|---|---|---|
--ds-loading-size |
Dot diameter | 0.3em |
--ds-loading-gap |
Gap between dots | 0.25em |
--ds-loading-spinner-size |
Spinner/morph diameter | 1em |
--ds-loading-bar-height |
Bar thickness | 3px |
--ds-loading-label-size |
Visible text size | 0.8125em |
--ds-loading-label-gap |
Gap between indicator and text | 0.625em |
--ds-loading-bar-label-gap |
Gap between bar and its text line | 0.375em |
--ds-loading-duration |
Animation speed (all variants) | per-variant (1.2–2s) |