The face of a voice agent: a sphere of ink dots that waves with the voice, orbits while thinking and ripples while speaking.
'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
pnpm add @brand-studio/uinpm install @brand-studio/uiyarn add @brand-studio/uibun add @brand-studio/uiInstall the peer dependencies
npm install react react-domImport the stylesheet once
import '@brand-studio/ui/styles.css';Wrap your app in a brand theme
import { BrandTheme, VoiceOrb } from '@brand-studio/ui'; import brand from './brand.json'; <BrandTheme palette={brand.tokens} mode="system"> {/* your app */} </BrandTheme>
Usage
import { VoiceOrb } from '@brand-studio/ui';<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.
labelshows 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 | '' |