Skip to main content

​
Orb component API

Orb is the main orb-ui component. It can run in controlled mode with explicit state and volume props, or through a provider adapter. 
import { Orb } from 'orb-ui'
;<Orb state="listening" volume={0.4} theme="circle" size={240} />

​
Props

PropTypeDefaultDescription
stateOrbStateadapter state or idleCurrent voice agent state. In controlled mode, pass this directly.
volumenumberadapter volume or 0Audio volume from 0 to 1. In controlled mode, pass this directly.
adapterOrbAdapternoneProvider adapter that subscribes to state and volume updates.
themeOrbThemedebugVisual theme: debug, circle, or bars.
sizenumber200Component size in pixels.
classNamestringnoneOptional class name for the rendered theme.
styleReact.CSSPropertiesnoneOptional inline styles for the rendered theme.
disabledbooleanfalseDisables clickable themes and debug start/stop controls.
idstringnoneForwarded to the rendered orb control/container.
data-*string/primitivenoneForwarded to the rendered orb control/container, useful for tests.
aria-labelstringgenerated when neededAccessible label for clickable circle and bars controls.
onStart() => voidadapter startStart handler used by the debug theme and clickable themes.
onStop() => voidadapter stopStop handler used by the debug theme and clickable themes.

​
States

type OrbState = 'idle' | 'connecting' | 'listening' | 'speaking' | 'error'
Use these states consistently across providers so your product has one voice UI language even when the underlying SDK changes.

​
Themes

type OrbTheme = 'debug' | 'circle' | 'bars'
  • debug: visible state and start/stop controls while integrating.
  • circle: the primary animated voice orb.
  • bars: waveform-like audio activity.
When an adapter or onStart/onStop handler is provided, circle and bars render as <button type="button"> controls with native keyboard activation. If there is no visible label, pass aria-label.

​
Adapter interface

interface OrbAdapter {
  subscribe(callbacks: {
    onStateChange: (state: OrbState) => void
    onVolumeChange: (volume: number) => void
  }): () => void
  start?: () => void | Promise<void>
  stop?: () => void | Promise<void>
}
Adapters normalize provider SDK events into orb-ui state and volume. If a provider is not supported yet, use controlled mode first and turn that mapping into an adapter later.
Last modified on June 5, 2026