Skip to main content
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