Matrix Orb React component for Tailwind CSS v4
v1.0.1Updated in 1.2.1
A React AI voice orb drawn as a dot matrix on canvas that animates through idle, listening and thinking states.
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.
Matrix Orb is a free React component in the React AI components category, written in TypeScript for React 19 and Tailwind CSS v4. It installs as source with npx wingo-ui@latest add matrix-orb, together with UIProvider.
Add to a project
Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup
npx wingo-ui@latest add matrix-orbUsage
Import MatrixOrb from @/components/ui/matrix-orb.
"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
statedefault"idle""idle" | "listening" | "thinking"Which animation the orb plays. Changes blend in place instead of restarting the loop.
sizedefault240numberDiameter of the orb in pixels. The dot grid spans 74% of it and the canvas tracks devicePixelRatio, so zooming stays sharp.
colordefault"#F75001"stringAny CSS color for the dots.
dotsdefault11numberHow many dots across the grid. Rounded, with a minimum of 3; dots outside the circle are skipped so the outline stays round.
speeddefault1numberHow fast the ripples and orbiters move: 1 is the original pace, 0 holds still. Changing it bends the motion without a restart.
spreaddefault0.74numberShare of the canvas the dot grid covers, 0.2 to 1.
dotScaledefault0.6numberLargest dot radius as a share of the spacing between dots; above 0.5 neighbours touch at full intensity.
showLabeldefaulttruebooleanShows the state caption under the orb. Hidden, it stays in the page as a screen reader status.
leveldefault0numberHow 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.
labelsPartial<Record<MatrixOrbState, string>>Caption under the orb, per state. Missing keys fall back to "Idle", "Listening" and "Thinking".
classNamestringExtra 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.
Dependencies
Files
- components/ui/matrix-orb.tsx
FAQ
Is the React Matrix Orb component free?
Yes. The source is free and needs no account: copy it from the Code tab or install it with the CLI.
How do I install Matrix Orb?
Run npx wingo-ui@latest add matrix-orb. It also adds the Wingo UI item it builds on (UIProvider). With shadcn, run npx shadcn@latest add https://wingo-ui.com/r/matrix-orb.json.