Skip to main content

​
Quickstart

Install orb-ui from npm: 
npm install orb-ui
Provider adapters also need their provider SDK installed in your app: 
npm install orb-ui @vapi-ai/web
npm install orb-ui @elevenlabs/client

​
Controlled mode

Controlled mode is the universal fallback. Use it when your app already owns the voice session and can provide a conversation state plus normalized volume. 
import { Orb } from 'orb-ui'

export function VoiceAgentStatus({ state, volume }) {
  return <Orb state={state} volume={volume} theme="circle" size={240} />
}
The state can be one of:
  • idle
  • connecting
  • listening
  • speaking
  • error
Volume should be a number from 0 to 1.

​
Vapi

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" />
}

​
ElevenLabs

import { Conversation } from '@elevenlabs/client'
import { Orb } from 'orb-ui'
import { createElevenLabsAdapter } from 'orb-ui/adapters'

const adapter = createElevenLabsAdapter(Conversation, {
  agentId: 'your-agent-id',
})

export function ElevenLabsVoiceUI() {
  return <Orb adapter={adapter} theme="bars" aria-label="Start ElevenLabs assistant" />
}

​
Themes

Start with:
  • circle for a primary assistant orb.
  • bars for waveform-like audio activity.
  • debug while verifying state and volume changes.
Clickable circle and bars themes render as keyboard-accessible buttons when you provide an adapter or onStart/onStop handler. Add an aria-label if the surrounding UI does not already label the control. Use the voice states guide when you are deciding how each state should appear in your product.
Last modified on June 5, 2026