Loading Area
A loading area: a surface that signals a process in progress, from two composable parts.
- A loading visual — by default the halftone dot field (
field): a faint dot lattice with a couple of soft, brighter zones that drift across it continuously (like the “image generating” dot cards), so different areas seem to render over time. The dots are a CSSbackground(no per-dot DOM), so it tiles to any size cheaply. - A label zone, placed with
labelPosition(centerdefault, ortop/bottom/left/right). It shows any combination of:- a live
statusmessage (“Connecting…”, “Rendering…”), - a
valuepercentage (shown asN%), - a
detailline — free text for bytes or a file count (“48 MB of 128 MB”, “3 of 8 files”).
- a live
The dot field and an explicit indicator are alternatives, never stacked (no
loader on a loader): turn field off and put a different loader — e.g. a
Loading spinner — into the
indicator snippet to use that as the area’s loader instead.
When the process finishes, set loading={false}: LoadingGenerationArea renders its
children (the real content) in place of the placeholder, with a gentle fade.
Unlike the inline Loading variants, LoadingGenerationArea covers a surface; use Loading
for an inline indicator next to text or in a button.
Import
Section titled “Import”<script> import LoadingGenerationArea from "@invisible-ui/svelte/LoadingGenerationArea.svelte";</script><script setup> import { LoadingGenerationArea } from "@invisible-ui/vue";</script>import { LoadingGenerationArea } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-loading-generation-area></ds-loading-generation-area>Give it a sized, positioned container (or drop it in as a filling layer). Add a
label zone (position + status / percentage / detail), and optionally an explicit
indicator through the indicator snippet:
<div style="position: relative; aspect-ratio: 16 / 10;"> <!-- Percentage + file count in a bottom label zone --> <LoadingGenerationArea labelPosition="bottom" status="Rendering" detail="3 of 8 files" /></div>
<div style="position: relative; aspect-ratio: 16 / 10;"> <!-- A plain area (no dot field) with an explicit spinner via the snippet --> <LoadingGenerationArea field={false} label="Loading"> {#snippet indicator()}<Loading variant="spinner" decorative />{/snippet} </LoadingGenerationArea></div>When the data arrives, flip loading and the children replace the
placeholder (with a gentle fade):
<LoadingGenerationArea loading={pending} status="Generating image"> <!-- the generated result (an image, a mock, any content) — shown once `pending` is false --> <img src={url} alt="Generated image" style="width: 100%; height: 100%; object-fit: cover;" /></LoadingGenerationArea>In plain HTML, import the Elements registration entry point and use the same loading-to-content contract:
<ds-loading-generation-area status="Generating image" value="40" detail="3 of 8 files"> <img src="result.png" alt="Generated image" /></ds-loading-generation-area>
<script> const area = document.querySelector("ds-loading-generation-area"); area.setAttribute("loading", "false");</script>In React, indicator and children take markup:
<LoadingGenerationArea loading={pending} status="Generating image" value={progress}> <img src={url} alt="Generated image" /></LoadingGenerationArea>| Prop | Type | Default | Description |
|---|---|---|---|
label | string | undefined | undefined | Accessible name. Defaults to the i18n catalog's "Loading…". |
decorative | boolean | false | Hide from assistive tech (the surrounding region announces the state). |
loading | boolean | true | Whether the process is still running. While true (default) the loading placeholder is shown; set it to false when done and children (the real content) is rendered in its place. |
field | boolean | true | Show the dot field as the backdrop. |
labelPosition | "center" | "top" | "bottom" | "left" | "right" | "center" | Where the label/indicator zone sits over the area. |
status | string | undefined | undefined | Live status message — announced on every change. |
value | number | null | null | Percentage (0–100), shown as "N%". |
detail | string | undefined | undefined | Extra detail line, e.g. "48 MB of 128 MB" or "3 of 8 files". |
indicator | Snippet | undefined | undefined | A loader shown in the label zone, e.g. a spinner when field is off. |
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | undefined | Accessible name. Defaults to the catalog's "Loading…". |
decorative | boolean | false | Hide from assistive tech (the surrounding region announces the state). |
loading | boolean | true | Whether the process is still running. While true (default) the loading placeholder is shown; set it to false when done and the default slot (the real content) is rendered in its place. |
field | boolean | true | Show the dot field as the backdrop. |
labelPosition | LoadingGenerationAreaPosition | "center" | Where the label/indicator zone sits over the area. |
status | string | undefined | Live status message, announced on every change. |
value | number | null | null | Percentage (0–100), shown as "N%". |
detail | string | undefined | Extra detail line, e.g. "48 MB of 128 MB" or "3 of 8 files". |
Slots: default, indicator.
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Accessible name. Defaults to the catalog's "Loading…". |
decorative | boolean | false | Hide from assistive technology (the surrounding region announces the state). |
loading | boolean | true | Whether the process is still running. While true (default) the loading placeholder shows; set it to false when done and children (the real content) render in its place. |
field | boolean | true | Show the dot field as the backdrop. |
labelPosition | LoadingGenerationAreaPosition | "center" | Where the label and indicator zone sits over the area. |
status | string | — | Live status message, announced on every change. |
value | number | null | null | Percentage (0 to 100), shown as "N%". |
detail | string | — | Extra detail line, such as "48 MB of 128 MB" or "3 of 8 files". |
indicator | ReactNode | — | A loader shown in the label zone, such as a spinner when field is off. |
children | ReactNode | — | The real content, rendered once loading is false. |
| Attribute | Reactive | Description |
|---|---|---|
label | yes | |
decorative | yes | |
loading | yes | |
field | yes | |
label-position | yes | |
status | yes | |
value | yes | |
detail | yes |
Reactive attributes re-render the element when they change after the first render.
Accessibility
Section titled “Accessibility”- A polite
role="status"with an accessible name (label; when omitted it comes from the i18n catalog, soLocaleProviderlocalizes it) — it announces the loading state like the other indicators. - When
statusis set it drives the announcement (the region isaria-atomic, so each new message is read in full); thevaluepercentage anddetailare visible butaria-hidden, so a fast-ticking value isn’t re-announced. - Set
decorativewhen the surrounding region already announces that it is busy (e.g. anaria-busycontainer) — the field is then hidden from assistive tech. - The drift respects
prefers-reduced-motion: the animation stops and the glows hold still (a gentle static brightening).
Theming
Section titled “Theming”Colors follow currentColor (set color on the container). Density and speed
are themeable:
| Token | Purpose | Default |
|---|---|---|
--ds-loading-generation-area-dot |
Resting (grey) dot radius — kept tiny | 1px |
--ds-loading-generation-area-dot-lit |
Lit dot radius (normal size, under a zone) | 2.5px |
--ds-loading-generation-area-gap |
Distance between dots | 1.1rem |
--ds-loading-generation-area-duration |
Drift cycle length | 7s |
--ds-loading-generation-area-min-height |
Fallback min height | 6rem |