# Dot matrix wave (goodtabs UI)

A grid of dots whose radius rides a slow wave, drawn in raw WebGL on theme tokens.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/dot-matrix-wave.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/dot-matrix-wave`

## Usage

```tsx
import { DotMatrixWave } from "@/components/ui/dot-matrix-wave"

<DotMatrixWave clearing={0.6} className="grid h-96 place-items-center">
  <h2>All systems calm</h2>
</DotMatrixWave>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| cell | `number` | `12` | Distance between dots in CSS pixels. |
| speed | `number` | `1` | Multiplies the wave's speed. |
| clearing | `number` | `0` | Radius of a calm area in the middle for content, as a fraction of the short side. |

## When to use

- A hero or section background that should feel alive without any colour
- Behind one short heading, with a clearing so the text keeps its contrast
- Status or empty states where a little movement says the system is awake

## When not to use

- Behind long text, even with a clearing, because the dots compete with reading
- More than two or three times on a page: browsers cap live WebGL contexts near 16
- Under a card grid, where a plain background is calmer

## Notes for agents

- The element needs a height. It fills its box and does nothing to set one
- It installs components/ui/shader-canvas.tsx, which pauses off screen, follows the theme and handles reduced motion
- Under reduced motion it draws one frame, and without WebGL a CSS dot grid shows through
- The canvas is aria-hidden, so never put information in the field. No GSAP is involved here

## The maths

- Dot radius is cell / 2 × mix(0.3, 0.9, w²). Squaring the wave w keeps most dots small and lets a few swell.
- Two sines at unrelated angles sum to a swell with no visible period: 0.5 + 0.25 × (sin a + sin b) stays in 0 to 1.
- Device pixel ratio caps at 1.5, which cuts shaded pixels on a 3x phone by 1 - 1.5² / 3² = 75 percent.

Docs: https://ui.goodtabs.co/components/dot-matrix-wave