Skip to content

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)

Team activity

12 updates this week

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.

<script>
import Loading from "@invisible-ui/svelte/Loading.svelte";
</script>

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).

PropTypeDefaultDescription
variant"dots" | "spinner" | "bar" | "typing" | "morph""dots"Indicator shape: pulsing dots or a rotating spinner arc.
valuenumber | nullnullCompletion 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.
labelstring | undefinedundefinedAccessible name announced by the status role.
showLabelbooleanfalseAlso render the label as visible text next to the indicator.
showValuebooleanfalseShow the percentage (from value) as visible text.
detailstring | undefinedundefinedExtra visible detail, e.g. "3 of 8 files" or "48 MB of 128 MB".
decorativebooleanfalseHide from assistive tech (the surrounding region announces the state).
statusstring | undefinedundefinedLive 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.
delaynumber0No-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).
overlaybooleanfalseRender as a centered overlay filling the nearest positioned ancestor — the built-in busy-region pattern. Mark that region aria-busy="true".
veilbooleantrueWith 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.

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.

  • By default the indicator is a polite role="status" with an accessible name (label; when omitted it comes from the i18n catalog, so LocaleProvider localizes it). A determinate bar is a progressbar with aria-value*, and detail doubles as its aria-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 decorative when 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.
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)