# Matrix Orb

> A React AI voice orb drawn as a dot matrix on canvas that animates through idle, listening and thinking states.

- Type: React component (AI Kit)
- Access: Free (the source is open to everyone)
- Version: 1.0.1
- Install: `npx wingo-ui@latest add matrix-orb`
- Docs: https://wingo-ui.com/components/matrix-orb

## Interaction

Switch the orb between its idle, listening and thinking states. Idle breathes softly, listening ripples out from the center and blooms with the level, thinking sends bright spots orbiting through the grid. Changing state mid-animation blends from whatever is on screen while the orb springs to its new scale, and the caption below updates for screen readers. Honors prefers-reduced-motion by drawing a still frame per state.

## Installation

```bash
npx wingo-ui@latest add matrix-orb
```

The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add https://wingo-ui.com/r/matrix-orb.json`

Files:

- `components/ui/matrix-orb.tsx`

Wingo UI dependencies (installed automatically):

- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
"use client"

import { useState } from "react"
import MatrixOrb, { type MatrixOrbState } from "@/components/ui/matrix-orb"

export function Demo() {
  const [state, setState] = useState<MatrixOrbState>("idle")

  return (
    <MatrixOrb
      state={state}
      onClick={() => setState(state === "idle" ? "listening" : "idle")}
      className="cursor-pointer"
    />
  )
}

// drive the bloom yourself with any value from 0 to 1
// <MatrixOrb state="listening" level={level} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state?` | `"idle" \| "listening" \| "thinking"` | `"idle"` | Which animation the orb plays. Changes blend in place instead of restarting the loop. |
| `size?` | `number` | `240` | Diameter of the orb in pixels. The dot grid spans 74% of it and the canvas tracks devicePixelRatio, so zooming stays sharp. |
| `color?` | `string` | `"#F75001"` | Any CSS color for the dots. |
| `dots?` | `number` | `11` | How many dots across the grid. Rounded, with a minimum of 3; dots outside the circle are skipped so the outline stays round. |
| `speed?` | `number` | `1` | How fast the ripples and orbiters move: 1 is the original pace, 0 holds still. Changing it bends the motion without a restart. |
| `spread?` | `number` | `0.74` | Share of the canvas the dot grid covers, 0.2 to 1. |
| `dotScale?` | `number` | `0.6` | Largest dot radius as a share of the spacing between dots; above 0.5 neighbours touch at full intensity. |
| `showLabel?` | `boolean` | `true` | Shows the state caption under the orb. Hidden, it stays in the page as a screen reader status. |
| `level?` | `number` | `0` | How far the orb blooms while listening, 0 to 1 (clamped), for example a live microphone level. Leave it out and a built-in envelope drives the bloom. |
| `labels?` | `Partial<Record<MatrixOrbState, string>>` |  | Caption under the orb, per state. Missing keys fall back to "Idle", "Listening" and "Thinking". |
| `className?` | `string` |  | Extra classes merged onto the root element (data-slot="matrix-orb", with data-state set to the current state). Other div props are spread onto it too. |

## Examples

- **Driving the bloom with level**: Pass level (0 to 1), for example a live microphone volume, and the listening bloom follows it. Leave it out and a built-in envelope animates it instead.
- **A voice assistant turn**: Ask, and the orb listens, thinks while the answer loads, then rests while the reply shows below it.
- **Colors and density**: Any CSS color for the dots, and dots from a coarse 7 to a fine 17 across.
- **Small inline status**: At 48px with fewer, bigger dots it works as a compact thinking indicator next to a line of text.

## See also

- [Fluid Orb](https://wingo-ui.com/components/fluid-orb) ([Markdown](https://wingo-ui.com/components/fluid-orb.md))
- [Voice Input](https://wingo-ui.com/components/voice-input) ([Markdown](https://wingo-ui.com/components/voice-input.md))
- [Reasoning Indicator](https://wingo-ui.com/components/reasoning-indicator) ([Markdown](https://wingo-ui.com/components/reasoning-indicator.md))
- [Grid Reveal](https://wingo-ui.com/components/grid-reveal) ([Markdown](https://wingo-ui.com/components/grid-reveal.md))
- [Agent Status Card](https://wingo-ui.com/components/agent-status-card) ([Markdown](https://wingo-ui.com/components/agent-status-card.md))

---

Canonical: https://wingo-ui.com/components/matrix-orb
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt