# Dot Matrix
Jun 2026 · [Source](https://github.com/assistant-ui/assistant-ui/blob/main/packages/ui/src/components/assistant-ui/dot-matrix.tsx)
Every agent is doing something. Connecting, thinking, searching, streaming, waiting on a tool. A spinner can't tell you which; it spins the same for all of them. Text can, but it wraps and jumps and asks to be read. I wanted a status light you glance at, the way you read a traffic light. Twenty-five dots, and twenty ways to blink them.

## Twenty states

Two states would be easy: busy or done. An agent has more than two. Loading isn't thinking. Thinking isn't streaming. Searching isn't waiting on a tool. So each one gets its own motion: a twinkle, a wave off the center, a ripple, a column sweep, an equalizer. The ones that resolve get a glyph (a check, a cross, a bang) in the color you'd expect.

## How it works

The hard part isn't the patterns; it's the change between them. You can't fade an animation in or out. Add it or take it away and the dots just snap. So nothing animates the transition. The dots are always animating; what moves is the amplitude. Each dot's bright and dim opacity live in registered CSS custom properties, and those carry a transition. Change the state and the bounds ease to new values, so every dot cross-fades into its next pattern instead of cutting. It reads as one surface breathing, not twenty-five dots restarting.

The twinkle is deterministic. Multiply each index by a prime and the dots a grid-stride apart fall into step, marching in columns instead of sparkling; a bit-mixing hash scatters them. It also means the server and the client land on the same delays, so nothing flickers on the first paint.

## Any size

It's drawn from the current text color, so it sizes like text and themes like text. Tuck it inline beside a label, or let it fill a card. Nothing rasterizes; nothing blurs.

## Usage

One prop. It ships as a standalone component in assistant-ui's registry; add it with the shadcn CLI, then hand it a state. The [full reference](https://www.assistant-ui.com/docs/ui/dot-matrix) lives in the docs.

```tsx

  return <DotMatrix state={isRunning ? "loading" : "success"} />;
}
```

## Just a dot matrix

No runtime, no dependencies, no animation loop in JavaScript. A server component that happens to move.