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. The Vapi web SDK does not currently expose local microphone input levels through the adapter event stream, so this adapter does not emit inputVolume while listening. If your app already meters the microphone separately, pass a controlled signal to Orb. 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 smooths Vapi’s assistant volume events before emitting outputVolume. It also debounces short speaking-to-listening changes so normal turn boundaries do not create distracting visual flicker.

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, 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. The current Vapi event stream used by this adapter provides assistant output levels, not the local microphone level. This is expected. Supply a custom inputVolume through controlled mode if microphone-reactive listening is important to the design. 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 missing local input meter is acceptable or supplied through controlled mode.
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