Loading…

Grid Loader

beta

Indeterminate loading indicators on a grid of cells — 48 patterns (and 17 SmoothUI alias names) that pulse or stagger, plus sequence, thinking and matrix.

Feedback
1 file
1 npm package
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add grid-loader

npm packages installed: class-variance-authority.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { GridLoader } from "@/components/ui/grid-loader";

Examples

Every example the tests run, live and operable, side by side.

Default
Gallery
Sizes
Inherits Colour

API

Generated from the component's own types, so a prop cannot appear here without existing.

<GridLoader>

Prop	Type	Default
`glow` A soft halo around each lit cell. Reads best on a dark surface.	`boolean`	`false`
`label` Announced to assistive technology while the loader is visible. Omit it when the loader sits inside something that already reports its busy state — announcing twice is worse than not announcing at all.	`string`	—
`mode` How the lit cells of a pattern move: together (`pulse`) or one by one in reading order (`stagger`). `sequence`, `thinking` and `matrix` have their own motion and ignore it.	`GridLoaderMode`	`"pulse"`
`rounded` Circular cells instead of rounded squares.	`boolean`	`false`
`size`	`"sm" \| "md" \| "lg" \| "xl"`	`"md"`
`speed` Cycle length: `slow` 1.5s, `normal` 0.8s, `fast` 0.4s — still scaled by the indicator motion scale. `thinking` and `matrix` keep their own tempo.	`GridLoaderSpeed`	`"normal"`
`variant` Which pattern to play.	`GridLoaderVariant`	`"plus-hollow"`

Plus every attribute of <span> except children.

Accessibility

Renders aria-hidden by default so it does not announce inside controls that already expose a busy state. Pass `label` to announce it standalone via role="status". Under reduced motion it slows rather than stopping, because a frozen loader reads as a hang.

Quality

Measured from the source and its tests at build time.

All scores

7/7

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — does not apply
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — does not apply
className merged — passes
Visible focus — does not apply
No fixed widths — passes

Prop

Type

Default

glow

A soft halo around each lit cell. Reads best on a dark surface.

boolean

false

label

Announced to assistive technology while the loader is visible. Omit it when the loader sits inside something that already reports its busy state — announcing twice is worse than not announcing at all.

string

—

mode

How the lit cells of a pattern move: together (pulse) or one by one in reading order (stagger). sequence, thinking and matrix have their own motion and ignore it.

GridLoaderMode

"pulse"

rounded

Circular cells instead of rounded squares.

boolean

false

size

"sm" | "md" | "lg" | "xl"

"md"

speed

Cycle length: slow 1.5s, normal 0.8s, fast 0.4s — still scaled by the indicator motion scale. thinking and matrix keep their own tempo.

GridLoaderSpeed

"normal"

variant

Which pattern to play.

GridLoaderVariant

"plus-hollow"