Dot matrix loader
ProSix dot grid loaders that play a pattern while waiting, fill in their own order as progress arrives and resolve into a check or cross drawn in dots.
- Wave
- Spiral
- Rain
- Ripple
- Snake
- Scan
- An upload, export or sync tile that starts without a size and later reports progress.
- A small status mark on a device, job or pipeline card where a spinner would feel generic.
- A loading state that should end in a clear, in place success or failure.
- Inside a button or next to text at 16 to 24 px: use morph-loader, which is drawn for that size.
- When the step name and elapsed time matter more than the animation: use status-loader.
- For page level progress across the width of a layout: use progress.
Installation
Pro source and install commands unlock with a Pro plan.
import { DotMatrixLoader } from "@/components/arc/dot-matrix-loader/dot-matrix-loader"; export function UploadStatus({ upload }: { upload: Upload }) { return ( <DotMatrixLoader variant="rain" state={upload.error ? "error" : upload.done ? "success" : "loading"} progress={upload.total ? upload.sent / upload.total : undefined} label={`Uploading ${upload.name}`} successLabel="Upload complete" errorLabel="Upload failed" /> );}DotMatrixLoader
A 7 by 7 grid of dots that plays a pattern while the amount of work is unknown, fills in the pattern's own order as soon as progress arrives and resolves into a check or a cross drawn in dots. Six variants: wave sends a diagonal swell across the grid and fills left to right; spiral turns two arms around the center and fills like a clock hand sweeping from twelve; rain drops a column of light down each column at its own pace and fills from the bottom like a tank; ripple sends rings out from the center and fills as a growing disc; snake runs three snakes around the nested rings in alternating directions and fills ring by ring from the outside in; scan sweeps a line up and down with a phosphor afterglow and fills like a printer, row by row. Every change continues from where each dot is: the pattern hands off into the fill, the fill hands off into the glyph and back.
variant"wave" | "spiral" | "rain" | "ripple" | "snake" | "scan""wave"Pattern the dots play while loading, and the order they fill in once progress arrives. Changing it while loading continues from the current dots.state"loading" | "success" | "error""loading""success" fades the grid out from the center and draws a check in dots along its stroke, "error" draws a cross and gives the grid a short damped shake. Setting "loading" again releases the glyph back into the pattern.progressnumber–Progress from 0 to 1. Leave undefined while the amount of work is unknown. Filled dots rest a step below full and the leading dot is brightest; unfilled dots keep a faint trace of the pattern so the grid never looks stalled.sizenumber48Rendered width and height in px. Dots scale with it; 32 to 96 reads best.accentstring–Any CSS color for the dots while loading. Defaults to the accent. Success and error use --success and --danger; override --dot-matrix-success and --dot-matrix-error to change them.labelstring"Loading"Accessible name of the progress bar while loading.successLabelstring"Done"Announced politely, and the accessible name, when the state becomes success.errorLabelstring"Failed"Announced politely, and the accessible name, when the state becomes error.decorativebooleanfalseHides the loader from assistive technology, for loaders inside a button or a region that already announces its state.classNamestring–Class on the root element.styleCSSProperties–Inline styles on the root element.- While loading the drawing is a role="progressbar" named by label. With progress it carries aria-valuemin, aria-valuemax and a rounded aria-valuenow; without it it is an indeterminate progress bar.
- Once resolved it becomes role="img" named by successLabel or errorLabel, and a polite live region announces the same text once. Nothing is announced while loading, so a page of loaders stays quiet.
- The result never relies on color alone: success and failure are a check and a cross, not just green and red dots.
- decorative hides the whole loader and its live region, for use inside a control that has its own label and status.
- One requestAnimationFrame loop per loader writes each dot's radius and opacity straight to the SVG. React renders only when props change. Writes are skipped when a value has not changed, and a settled check or cross stops the loop completely.
- Handing off from pattern to progress blends the two on a critically damped spring, and displayed progress follows the prop on its own spring, so a jump from 20 to 80 percent sweeps through the fill order instead of snapping.
- Each dot has its own springs for showing the result and for which glyph it belongs to. The check is drawn along its stroke 45 ms a dot while the other dots fade out from the center; glyph dots overshoot slightly as they land. Changing state mid transition continues from the current dots.
- The cross lands with a short damped horizontal shake. The dot color crossfades to --success or --danger in CSS.
- The loop pauses offscreen and in background tabs, and resumes where it left off.
- With reduced motion the pattern is frozen in one representative pose and the whole grid breathes its opacity slowly to show work is ongoing. Progress fills and glyphs appear quickly without stagger, overshoot or shake.
- The loader is a fixed size square; it never changes size between states, so surrounding layout never shifts.
- Dots are drawn in a 70 unit viewBox and scale crisply to any size; below 32 px the grid gets dense, so prefer morph-loader there.
- 49 SVG circles, updated only when their rounded value changes. Six loaders on one page cost well under a millisecond a frame.
- The loop stops when resolved and settled, pauses offscreen with an IntersectionObserver and in hidden tabs.
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
- Pick it for a compact, characterful loader in a card, an upload tile, a device or IoT screen, or a retro or technical product surface. For a plain button spinner use morph-loader; for ring shaped progress use halo-loader.
- Pass progress as soon as you know it and keep passing undefined until then; the loader hands off without a jump. Set state to success or error when the job ends, even if progress never reached 1.
- Match the variant to the job: rain and scan for uploads and scanning, ripple and pulse like work for network activity, snake and spiral for processing, wave as a neutral default.
- In grids of many loaders set decorative on all but one so screen readers hear one announcement.
The full library index for assistants is at /llms.txt.