# Orb

A React component in [Beamline](https://beamline.io/)'s [Voice & audio](https://beamline.io/components/voice) category. Live demo: https://beamline.io/components/orb

The agent's presence: a thin ring of light around a lens in the brand's hue that holds still at rest, sends an arc round while thinking and widens with the voice; from a 16px agent mark to a 240px voice screen.

## Use it for

- The agent's mark beside its messages and in the reasoning header.
- Voice screens and calls: listening and talking widen the ring with the volume.
- A single busy indicator for an agent (thinking).

## Not for

- Status in dense UI ([spinner](https://beamline.io/components/spinner)).
- People ([avatar](https://beamline.io/components/avatar)).
- Ambient light around a surface ([glow](https://beamline.io/components/glow)).
- A precise level ([bar-visualizer](https://beamline.io/components/bar-visualizer), [live-waveform](https://beamline.io/components/live-waveform)).

## Anatomy

- halo (bloom outside the ring)
- sphere (the lens)
- one (inner light, rises with the voice)
- two (the ring of light)
- shine (the arc that goes round while thinking)

## Variants

- **agentState**: null (idle), thinking, listening, talking
- **size**: any: size-4 … size-60 via className; at 32px and under the bloom hides and the ring thickens
- **colors**: brand-derived --pui-orb-1/2 (default), any two colours (a voice's own ring)

## States

- idle (still: the ring at rest, its lit side offset by seed; costs nothing)
- thinking (one bright arc goes round the ring; the ring dims under it)
- listening (a neutral ring widens with input volume)
- talking (the ring widens in colour and the lens lights with output volume)
- off screen or hidden tab (paused: data-paused)
- reduced motion (nothing turns: the thinking arc stands still; listening and talking hold a wider ring)

## Keyboard

- None; decorative (aria-hidden) unless given a label, then role img.

## Motion

Compositor transforms and opacity only, and only while the agent thinks, listens or talks; idle runs no loop. Thinking turns one arc every 4 × --pui-duration-considered. The one script is a volume read, ~30 writes a second, only while listening or talking, on screen and not under reduced motion; it sets --pui-level, which widens the ring and lights the lens. Under reduced motion nothing turns: the thinking arc stands still and listening or talking hold a wider ring.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `agentState` | `null \| "thinking" \| "listening" \| "talking"` | `null` |  |
| `label` | `string` | — | Accessible name; without it the orb is decorative. |
| `colors` | `[string, string]` | — | Two colours for the ring: its bright side and its fading side. Default: the brand's orb hues. |
| `colorsRef` | `RefObject<[string, string]>` | — | Live colours read each frame while reacting. |
| `getInputVolume / getOutputVolume` | `() => number` | — | 0–1 getters read while listening / talking. |
| `inputVolumeRef / outputVolumeRef` | `RefObject<number>` | — | The same as refs. |
| `volumeMode` | `"auto" \| "manual"` | `"auto"` | manual reads manualInput / manualOutput instead. |
| `manualInput / manualOutput` | `number` | — |  |
| `seed` | `number` | — | Turns where the light falls on the ring, so marks side by side never look stamped, and offsets the thinking arc. |
| `resizeDebounce` | `number` | — | Deprecated, no effect (kept for compatibility). |
| `style / ref` | `CSSProperties / native Ref` | — |  |
| `classNames` | `OrbClassNames` | — |  |

## Import

```tsx
import { Orb } from "@/components/orb/orb";
```

## Get it

Orb is part of Beamline: 190 React components and screens your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 one payment (regular $200), no subscription, a year of updates, one licence for your whole team. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Voice & audio

- [Audio player](https://beamline.io/components/audio-player): One audio element and its controls: play with a loading state, a scrub bar with time, skip, speed and a playlist whose rows play into the same player…
- [Bar visualizer](https://beamline.io/components/bar-visualizer): A row of bars that says what a voice agent is doing: a sweep while connecting, the person's voice while listening, a slow breath while thinking, the…
- [Conversation bar](https://beamline.io/components/conversation-bar): The control bar of a voice call with an agent: one button to call and hang up, the agent's state as bars, a call timer, mute, and typing when talking is…
- [Live waveform](https://beamline.io/components/live-waveform): Loudness drawn as it happens: a scrolling history of the microphone (or any live source) or its spectrum, a calm processing state while words are…
- [Matrix](https://beamline.io/components/matrix): A dot-matrix display: animated frame sets (loading, pulse, wave, syncing), text and digits in a 5×7 font, or a VU meter of levels or a live source. One…
- [Microphone selector](https://beamline.io/components/mic-selector): Choose the microphone, test it with a live level and mute it, with every permission and device state spelled out: not yet allowed, blocked (and how to…
- [Scrub bar](https://beamline.io/components/scrub-bar): A seekable timeline for audio or video: elapsed and total time, what has loaded, chapter marks, a time preview under the pointer, and the full keyboard…
- [Speech input](https://beamline.io/components/speech-input): A text field you can speak into: the mic dictates through any speech-to-text provider, the phrase being heard shows apart from the finished words, and…
- [Transcript viewer](https://beamline.io/components/transcript-viewer): A recording and its words together: the spoken word lights up as it plays and the transcript follows it, any word or paragraph time plays from there…
- [Voice button](https://beamline.io/components/voice-button): The control that starts and stops talking: click to toggle or hold to talk (pointer, Space, Enter or a global shortcut), with a live level while…
- [Voice picker](https://beamline.io/components/voice-picker): Choose a text-to-speech voice from a searchable list (name, accent, tone, use) and hear it first: each voice has its own orb, previews play one at a time…
- [Waveform](https://beamline.io/components/waveform): The shape of a recording: one bar per slice of loudness, fitted to any width, with the played part in the accent, unmeasured slices hatched and a loading…