# Voice Orb

> The face of a voice agent: a sphere of ink dots that waves with the voice, orbits while thinking and ripples while speaking.

```tsx
'use client';

import { useEffect, useState } from 'react';
import { DictationButton, MagnetTabs, VoiceOrb } from '@brand-studio/ui';
import type { VoiceOrbShape, VoiceState } from '@brand-studio/ui';

const states: VoiceState[] = ['idle', 'listening', 'thinking', 'speaking'];
const shapes: (VoiceOrbShape | 'state')[] = ['state', 'network', 'meridians', 'ribbon', 'morph'];

export default function VoiceOrbDemo() {
  const [state, setState] = useState<VoiceState>('listening');
  const [shape, setShape] = useState<VoiceOrbShape | 'state'>('state');
  const [mic, setMic] = useState(false);
  const [level, setLevel] = useState(0);
  // Without the microphone, a made-up voice drives the level.
  useEffect(() => {
    if (mic || (state !== 'listening' && state !== 'speaking')) { if (!mic) setLevel(0); return; }
    let frame = 0;
    const tick = (time: number) => { setLevel(Math.max(0, Math.sin(time / 180) * Math.sin(time / 530)) * 0.9); frame = requestAnimationFrame(tick); };
    frame = requestAnimationFrame(tick);
    return () => cancelAnimationFrame(frame);
  }, [mic, state]);
  return (
    <div style={{ width: '100%', display: 'grid', gap: 28, justifyItems: 'center' }}>
      <VoiceOrb state={state} level={level} size={140} shape={shape === 'state' ? undefined : shape} />
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12, alignItems: 'center', justifyContent: 'center' }}>
        <div style={{ maxWidth: '100%', overflowX: 'auto' }}>
          <MagnetTabs items={states.map(value => ({ value, label: value[0].toUpperCase() + value.slice(1) }))} value={state} onValueChange={value => setState(value as VoiceState)} aria-label="Orb state" />
        </div>
        <DictationButton label="Use my microphone" listening={mic} onListeningChange={on => { setMic(on); if (on) setState('listening'); }} onLevel={setLevel} />
      </div>
      <div style={{ maxWidth: '100%', overflowX: 'auto' }}>
        <MagnetTabs items={shapes.map(value => ({ value, label: value === 'state' ? 'State look' : value[0].toUpperCase() + value.slice(1) }))} value={shape} onValueChange={value => setShape(value as VoiceOrbShape | 'state')} aria-label="Orb shape" />
      </div>
    </div>
  );
}
```

## Installation

```sh
npm install @brand-studio/ui
```

React 18 or 19 is a peer dependency. Import the stylesheet once and wrap the app in a brand theme:

```tsx
import '@brand-studio/ui/styles.css';
import { BrandTheme, VoiceOrb } from '@brand-studio/ui';
import brand from './brand.json';

<BrandTheme palette={brand.tokens} mode="system">
  {/* your app */}
</BrandTheme>
```

## Usage

```tsx
import { VoiceOrb } from '@brand-studio/ui';
```

```tsx
<VoiceOrb state="listening" level={level} size={140} />
<VoiceOrb state="thinking" shape="network" />
```

`level` runs from 0 to 1. Feed it the microphone's loudness while listening (DictationButton's `onLevel` gives you this) or the agent's voice while speaking. Idle shows a ring that breathes, listening sends a wave through rows of dots, thinking runs dots round tilted orbits and speaking spreads ripples from the orb's face. Pass `shape` to swap in another look for every state: `network` joins dots with lines, `meridians` weaves dots along vertical lines, `ribbon` rolls a band of strokes round the sphere and `morph` re-forms a ring of dots into a circle, a triangle and a square. A shape runs at half speed while idle and swells with `level`. The dots take the ink colour, so the orb follows light and dark themes. Below 64 px it draws fewer, larger dots.

## Accessibility

- The orb is a status that says its state in words: Ready, Listening, Thinking or Speaking. `label` shows your own words instead.
- The drawing is hidden from screen readers.
- With reduced motion the orb holds still but still follows the level. It also stops drawing when it scrolls off screen.

## API Reference

| Prop | Type | Default |
|---|---|---|
| `state?` | `"idle" \| "listening" \| "speaking" \| "thinking"` | `'idle'` |
| `level?` | `number` | `0` |
| `size?` | `number` | `120` |
| `shape?` | `"meridians" \| "morph" \| "network" \| "ribbon"` | – |
| `label?` | `string` | – |
| `className?` | `string` | `''` |

Source: https://brandstudio.js.org/docs/components/voice-orb/
