--- title: "Loader" description: "Pure-CSS loading indicators in eight styles, from bouncing dots and waves to shimmering text, tuned with custom properties." url: "https://susonwaiba.github.io/htmx-ui/docs/components/loader" section: "Components" --- # Loader Pure-CSS loading indicators in eight styles, from bouncing dots and waves to shimmering text, tuned with custom properties. ```html

pulse

pulse-dot

dots

typing

wave

text-blink

text-shimmer

loading-dots

``` ## Markup - A loader is `.loader` plus one variant class. It needs no JavaScript: every variant is drawn and animated with CSS. - Dots and bars are empty child ``s (three for `.loader-dots` and `.loader-typing`, five for `.loader-wave`), each `aria-hidden="true"`. The pulse variants have no children: the element itself is the shape. - Give the loader `role="status"` and an accessible name: `aria-label`, or `` text after the dots. The text variants show their own text, which is read out. - The [`loader()` macro](#macro) writes all of this for you. ```html ``` ## Shapes `.loader-pulse` is a ring that breathes in and out; `.loader-pulse-dot` a single dot. `.loader-dots` bounces three dots, `.loader-typing` fades them in turn like a chat typing indicator, and `.loader-wave` raises and lowers a row of bars. ```html ``` ## Text The text variants animate the words themselves, in the muted text colour at the surrounding font size. `.loader-text-blink` fades the text in and out, `.loader-text-shimmer` sweeps a light band across it, and `.loader-loading-dots` writes an ellipsis one dot at a time. ```html Fetching results Thinking about your question Generating ``` ## Sizes `.loader-sm` and `.loader-lg` make the shapes 12px and 24px tall instead of 16px, and set the text variants in `text-xs` and `text-base`. For any other size set `--loader-size`; dots and bars are sized from it. ```html

Small Default Large

``` ## Customisation Every variant reads its look from custom properties on the `.loader`. Set them in a `style` attribute, or with Tailwind's arbitrary properties such as `[--loader-duration:2s]`. - `--loader-size`: the height of the shapes (`1rem`). - `--loader-duration`: one cycle of the animation (`1.2s`; the text variants `2s`, loading dots `1.4s`). The dots' and bars' stagger follows it. - `--loader-color`: the colour. Shapes use the current text colour, so `text-*` utilities work too; the text variants default to `muted-foreground`. - `--loader-highlight` and `--loader-spread`: the colour of the shimmer's light band (`foreground`) and its half-width, as a share of the sweep (`20%`). ### Speed ```html ``` ### Colour ```html Saving ``` ### Shimmer band A wider `--loader-spread` softens the band; a contrasting `--loader-highlight` tints it. ```html A narrow, sharp band A wide, soft band Tinted with the primary colour ``` > With `prefers-reduced-motion` set, nothing moves: every variant fades its opacity slowly instead, so the loader still reads as busy. ## In a button Shapes sit in a `.btn` like an icon. When the button text already says what's happening, pass `label=none` so the loader is hidden from screen readers. ```html ``` ## With htmx requests Add `.htmx-indicator` to show a loader only while a request runs. Inside a button it takes no space until then, and `.htmx-indicator-hide` swaps out an icon for it, as with the [spinner](https://susonwaiba.github.io/htmx-ui/docs/components/spinner#htmx). ```html

Refreshing

``` > The `/api/slow` endpoint is a mock that only exists under `bun run dev`. ## Macro `loader()` writes the variant's children, `role="status"` and the accessible name. Shapes are read out as `label`; text variants show `text` (or the label) and are read as it. ```jinja {% from "components/loader/loader.html" import loader %} {{ loader() }} {# three bouncing dots, "Loading" #} {{ loader("wave", size="lg", label="Uploading") }} {{ loader("text-shimmer", text="Thinking") }} {{ loader("pulse", label=none) }} {# decorative #} {{ loader("typing", class="htmx-indicator", attrs={"id": "typing"}) }} ``` ## Reference | Class | Description | | --- | --- | | `.loader` | The base: an inline flex box that holds the custom properties below. | | `.loader-pulse` | A ring breathing in and out. | | `.loader-pulse-dot` | A single pulsing dot. | | `.loader-dots` | Three bouncing dots (three child spans). | | `.loader-typing` | Three dots fading in turn, a typing indicator (three child spans). | | `.loader-wave` | Bars rising and falling (five child spans). | | `.loader-text-blink` | Text fading in and out. | | `.loader-text-shimmer` | Text with a light band sweeping across it. | | `.loader-loading-dots` | Text followed by "..." written one dot at a time (three child spans). | | `.loader-sm / .loader-lg` | 12px or 24px shapes; text-xs or text-base text. | | `--loader-size` | The height of the shapes (1rem). | | `--loader-duration` | One animation cycle (1.2s; text 2s, loading dots 1.4s). | | `--loader-color` | The colour (currentColor; text variants muted-foreground). | | `--loader-highlight / --loader-spread` | The shimmer band's colour (foreground) and half-width (20%). | | Macro | Description | | --- | --- | | `loader(variant="dots", text=none, size=none, label="Loading", class="", attrs=none)` | Writes a loader. label=none hides a shape from assistive technology; text sets a text variant's words. |