Vapi Voice UI for React

Vapi handles the voice agent platform layer. orb-ui handles the visible React UI layer: an animated voice orb, audio-reactive feedback, and predictable states that make a Vapi assistant feel present in your app.

Install

Install both orb-ui and the Vapi web SDK used by the adapter:

npm install orb-ui @vapi-ai/web

Use the adapter

import Vapi from '@vapi-ai/web'
import { Orb } from 'orb-ui'
import { createVapiAdapter } from 'orb-ui/adapters'

const vapi = new Vapi('your-public-key')
const adapter = createVapiAdapter(vapi, {
  assistantId: 'your-assistant-id',
})

export function VapiVoiceUI() {
  return <Orb adapter={adapter} theme="circle" aria-label="Start Vapi assistant" />
}

Create the Vapi client and adapter outside the render path, or memoize them when configuration is dynamic. Recreating either object on every render can replace event subscriptions while a call is active.

Session ownership

The adapter can start and stop the configured assistant, and it also observes calls started elsewhere through the same Vapi client. Activating an interactive orb calls vapi.start() with the configured assistantId; activating it again calls vapi.stop(). If the product already has labeled call controls, render a passive orb instead:

export function VapiCallSurface() {
  return (
    <section aria-label="Vapi conversation">
      <Orb adapter={adapter} theme="cloud" interactive={false} />
      <button onClick={() => void adapter.start?.()}>Start conversation</button>
      <button onClick={() => adapter.stop?.()}>End conversation</button>
    </section>
  )
}

State mapping

The adapter maps Vapi conversation lifecycle events into orb-ui state changes. The UI can then communicate:

connection startup
listening state
assistant speech
errors

Vapi assistant audio levels are emitted as outputVolume while the assistant is speaking. Microphone inputVolume comes from the existing local audio track exposed by the SDK’s public getDailyCallObject() method. The adapter does not request a second microphone stream or stop SDK-owned tracks. It follows track replacement and mute, and releases its meter when the call ends, errors, or the subscriber disconnects. Clients without this optional method retain assistant output metering and report zero input. The core mapping is:

Vapi event	Orb state
`vapi.start()`	`connecting`
`call-start`	`listening`
`speech-start`	`speaking`
`speech-end`	`listening`
`call-end`	`idle`
`error`	`error`

The adapter maps Vapi’s assistant volume events into the standard stable outputVolume envelope. It also debounces short speaking-to-listening changes so normal turn boundaries do not create distracting visual flicker. Most applications should use the shipped directional profiles. For a custom Vapi audio path, the adapter accepts inputVolumeCalibration, outputVolumeCalibration, onInputVolumeSample, and onOutputVolumeSample. Input diagnostics measure waveform RMS; output diagnostics report Vapi’s remote audio levels. createAudioContext can customize or disable the microphone meter. See volume calibration for the anchor semantics and guided profile generator.

Accessibility

When an adapter or onStart/onStop handler is provided, clickable circle and bars themes render as <button type="button"> controls. Pass an aria-label when no visible text labels the orb.

When to use controlled mode instead

Use controlled mode if your app wraps Vapi in its own session layer or combines Vapi with custom state. The Orb component does not need to own the provider SDK if your app already knows the voice signal.

<Orb signal={{ state: voiceState, inputVolume, outputVolume }} theme="circle" />

Controlled mode is the better fit when you combine Vapi with a separate microphone meter, tool status, human handoff, or application-owned call state. Keep the Vapi client lifecycle in your session layer and pass one normalized OrbSignal to the UI.

Troubleshooting

The orb never leaves idle. Make sure the adapter and the code starting the call share the same Vapi client instance. The adapter listens for lifecycle events on that object. Listening has little or no audio motion. Confirm that the Vapi client exposes getDailyCallObject(), the microphone is enabled, and Web Audio is available. SDK wrappers that hide that method can expose it or supply inputVolume through controlled mode. The interface starts multiple calls. Use either the interactive orb or your own start control as the primary action. When the product owns the controls, set interactive={false}. The orb stays in error after retrying. Confirm that the underlying Vapi call can start again and that the same subscribed client receives the new call-start event. Surface the provider error in adjacent recovery copy rather than relying on the visual alone.

Production checklist

The Vapi public key and assistant configuration are appropriate for browser use.
One stable client and adapter instance owns the current call.
The SDK’s local microphone track is available and produces input levels while listening.
Permission and provider errors have labeled retry actions.
Interactive behavior is disabled when separate call controls are present.
Start, stop, interruption, failure, and restart are tested in the real browser.

Positioning

orb-ui is not a Vapi replacement. It is a frontend UI layer for teams already building with Vapi or comparing voice agent stacks.

Start

Reference

Adapters

Guides

Vapi Voice UI for React

Install

Use the adapter

Session ownership

State mapping

Accessibility

When to use controlled mode instead

Troubleshooting

Production checklist

Positioning

​Install

​Use the adapter

​Session ownership

​State mapping

​Accessibility

​When to use controlled mode instead

​Troubleshooting

​Production checklist

​Positioning

​Related

Install

Use the adapter

Session ownership

State mapping

Accessibility

When to use controlled mode instead

Troubleshooting

Production checklist

Positioning

Related