# Dot matrix loader

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

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/dot-matrix-loader
- Markdown: https://uiarc.dev/components/dot-matrix-loader/markdown
- Source file: `registry/components/dot-matrix-loader/dot-matrix-loader.tsx`
- Dependencies: motion
- Keywords: special, loading, motion, new, loader, spinner, dot matrix, dots, grid, progress, determinate, indeterminate, upload, led, pixel, success, error, check, cross, wave, spiral, rain, ripple, snake, scan

## When to use

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

## When not to use

- 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

Dot matrix loader is part of Arc Pro. The live preview is public; the source and install command need Pro.

### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/dot-matrix-loader
```

### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

## Usage

```tsx
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"
    />
  );
}
```

## API reference

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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `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. |
| `progress` | `number` | – | 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. |
| `size` | `number` | `48` | Rendered width and height in px. Dots scale with it; 32 to 96 reads best. |
| `accent` | `string` | – | 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. |
| `label` | `string` | `"Loading"` | Accessible name of the progress bar while loading. |
| `successLabel` | `string` | `"Done"` | Announced politely, and the accessible name, when the state becomes success. |
| `errorLabel` | `string` | `"Failed"` | Announced politely, and the accessible name, when the state becomes error. |
| `decorative` | `boolean` | `false` | Hides the loader from assistive technology, for loaders inside a button or a region that already announces its state. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline styles on the root element. |

## Accessibility

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

## Motion

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

## Responsive behavior

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

## Performance

- 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

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

## Related

- [Morph loader](https://uiarc.dev/components/morph-loader/markdown): Tiny loaders that morph between shapes and fold into a check or a cross when done.
- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.
- [Skeleton morph](https://uiarc.dev/components/skeleton-morph/markdown): Loading skeletons that grow into the real content, block by block, instead of swapping.

## Also in loaders

- [Stretch refresh](https://uiarc.dev/components/stretch-refresh/markdown): Pull a feed down and a line stretches to tell you when to let go.
- [Feedback morph](https://uiarc.dev/components/feedback-morph/markdown): A feedback button that becomes a form, then a thank-you, in one shape.
- [Celebrate button](https://uiarc.dev/components/celebrate-button/markdown): A button that bursts confetti from its own edges on success while the label morphs to done.
- [Black hole](https://uiarc.dev/components/black-hole/markdown): A delete transition that pulls the chosen items into a tiny singularity while the rest of the list bends around it; undo spins them back out.
- [Slide to confirm](https://uiarc.dev/components/slide-to-confirm/markdown): A slide-to-confirm control. The thumb pulls a liquid fill behind it and makes the track swell. It snaps back on a spring if released early. Past the threshold, the track draws into the thumb and the chevron morphs into a success check, with pending and error states.
- [Charge session](https://uiarc.dev/components/charge-session/markdown): An EV or device charging card. Energy packets flow from a charger along the cable into the battery pack, which fills toward a draggable charge limit. The charge curve tapers near full, and power, energy, time to limit and cost update live. Stop charging drains the flow.
- [Arming switch](https://uiarc.dev/components/arming-switch/markdown): An aircraft style guarded switch for dangerous actions such as a production deploy. Lift the translucent red cover on its hinge, throw the chrome bat toggle until it snaps over center and the lamp flickers on, then press and hold the lamp to run the action. Closing the cover throws an armed switch back to safe.
- [Padlock toggle](https://uiarc.dev/components/padlock-toggle/markdown): A privacy switch drawn as a polished steel padlock. Push the shackle down or tap it: the shackle snaps into the body, the body bounces, the keyhole lights up in the accent and the label rolls from Public to Private. Unlocking pops the shackle against its collar and swivels it open.

## Guidance for AI tools

Dot matrix loader: Six 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. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt
