Orb component API

Orb is the main orb-ui component. It can run in controlled mode with explicit state and volume props, richer signal objects, or through a provider adapter.

import { Orb } from 'orb-ui'
;<Orb state="listening" volume={0.4} theme="circle" size={240} />

Props

Prop	Type	Default	Description
`signal`	`OrbSignal`	adapter signal	Current voice signal with state, input volume, and output volume.
`state`	`OrbState`	signal state or `idle`	Current voice agent state. Overrides signal and adapter state.
`volume`	`number`	signal volume or `0`	Audio volume from `0` to `1`. Overrides signal and adapter volume.
`adapter`	`OrbAdapter`	none	Provider adapter that subscribes to normalized signal updates.
`theme`	`OrbTheme`	`debug`	Visual theme: `debug`, `circle`, `bars`, `cloud`, or `radial`.
`size`	`number`	`200`	Component size in pixels.
`className`	`string`	none	Optional class name for the rendered theme.
`style`	`OrbStyle`	none	Inline styles, including the radial control surround variable.
`disabled`	`boolean`	`false`	Disables clickable themes and debug start/stop controls.
`interactive`	`boolean`	`true`	Allows the theme control to start and stop the session.
`id`	`string`	none	Forwarded to the rendered orb control/container.
`data-*`	`string`/primitive	none	Forwarded to the rendered orb control/container, useful for tests.
`aria-label`	`string`	generated when needed	Accessible label for clickable visual themes.
`onStart`	`() => void`	adapter start	Start handler used by the debug theme and clickable themes.
`onStop`	`() => void`	adapter stop	Stop handler used by the debug theme and clickable themes.

States

type OrbState = 'idle' | 'connecting' | 'listening' | 'thinking' | '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' | 'cloud' | 'radial'

debug: visible state and start/stop controls while integrating.
circle: the primary animated voice orb.
bars: waveform-like audio activity.
cloud: a soft atmospheric sphere with opposing input/output scale response.
radial: a four-lobe field with an input-reactive membrane and output-reactive twist.

When an adapter or onStart/onStop handler is provided, visual themes include a <button type="button"> control with native keyboard activation. radial uses a separate phone button while the other clickable visuals use the artwork itself. If there is no visible label, pass aria-label. The radial control’s cutout defaults to white. Set --orb-ui-radial-control-surround through the typed style prop when the orb sits on another surface:

<Orb adapter={adapter} theme="radial" style={{ '--orb-ui-radial-control-surround': '#101010' }} />

Set interactive={false} when the orb is only a visual status surface. The adapter remains the session controller, so external buttons can call its existing lifecycle methods.

<Orb adapter={adapter} theme="cloud" interactive={false} />
<button onClick={() => void adapter.start?.()}>Start conversation</button>
<button onClick={() => void adapter.stop?.()}>End conversation</button>

Adapter interface

interface OrbSignal {
  state: OrbState
  volume?: number
  inputVolume?: number
  outputVolume?: number
  error?: unknown
}

interface OrbAdapter {
  subscribe(listener: (signal: OrbSignal) => void): () => void
  start?: () => void | Promise<void>
  stop?: () => void | Promise<void>
}

Adapters normalize provider SDK events into orb-ui signals. If a provider is not supported yet, use controlled mode first and turn that mapping into an adapter later.

<Orb signal={{ state: 'listening', inputVolume: 0.35 }} />
<Orb signal={{ state: 'speaking', outputVolume: 0.72 }} />

Migrating callback-object adapters

orb-ui 0.5.0 removes the deprecated callback-object adapter API. Pass one complete signal to the listener whenever state or volume changes.

// Before 0.5
subscribe({ onStateChange, onVolumeChange }) {
  session.on('state', onStateChange)
  session.on('volume', onVolumeChange)
}

// 0.5.0+
subscribe(listener) {
  session.on('change', ({ state, inputVolume, outputVolume }) => {
    listener({ state, inputVolume, outputVolume })
  })
}

Custom adapters should implement OrbAdapter; the removed AdapterCallbacks and LegacyOrbAdapter types are no longer exported.

Start

Reference

Adapters

Guides

Orb component API

Props

States

Themes

Adapter interface

Migrating callback-object adapters

​Props

​States

​Themes

​Adapter interface

​Migrating callback-object adapters

​Related

Props

States

Themes

Adapter interface

Migrating callback-object adapters

Related