A React voice orb is the visible state layer for a voice agent. It should make listening, thinking,
speaking, and error states understandable at a glance while staying out of the way of the
conversation.
Build an animated voice orb in React
Start with a controlled Orb when you want to preview the component before connecting a live
voice provider:
This renders an animated voice orb in its listening state. For a production voice experience,
drive the state and volume from a real session. A fixed value is useful for previews and visual
tests, but it should not be used to imply that the microphone or assistant is active.
Simulate the full lifecycle
Before connecting a provider, build a small test surface that can show every supported state:
This makes theme selection and regression testing faster without opening a microphone or consuming
provider minutes.
Provider-backed orb
Use an adapter when the provider SDK owns the session.
Passive orb with separate controls
An orb can subscribe to an adapter without becoming the session control.
Use this structure when the product already has a call-control bar. The orb remains a status
visualization, and the labeled buttons continue to make sense with reduced motion or without the
canvas.
Custom controlled orb
Use controlled mode when a custom stack supplies a voice signal.
A signal should represent the current snapshot, not just the latest event. Include state and the
most recent normalized volumes together so the UI cannot display an old speaking level after it
returns to listening.
Direction-specific motion
The radial theme maps human input to its translucent outer membrane and agent output to the
twisting field inside the circle. Supply both volume directions through OrbSignal; Orb selects
the relevant value for the current state.
For a single legacy meter, volume remains available. Separate directions are preferable whenever
the integration can measure both sides because they help a theme distinguish “the app heard you”
from “the assistant is responding.”
Add accessible status copy
Animation should reinforce, not replace, a text description. Put a concise label near the orb and
announce meaningful lifecycle changes:
If the orb starts or stops a session, give it an aria-label. If separate controls own the session,
set interactive={false} and label those controls instead.
Test the integration
- Step through idle, connecting, listening, thinking, speaking, and error.
- Check silence, background noise, normal speech, and high volume.
- Deny microphone permission and verify that a recovery action appears.
- Start, stop, and start again to catch leaked provider listeners.
- Interrupt assistant speech and confirm the UI promptly returns to listening.
- Test keyboard navigation, reduced motion, and the text status without audio.
Design notes
- Do not animate aggressively while idle.
- Make listening and speaking visually distinct.
- Use thinking for processing gaps when the selected theme benefits from a distinct treatment.
- Keep error states obvious but not alarming.
- Pair the orb with a transcript or status label when users need more precision.
Use the complete voice agent UI guide to plan the production lifecycle.
Then continue with the themes and voice states reference, choose a provider
in the adapter overview, or connect an app-owned runtime with the custom
integration guide. Last modified on July 29, 2026