Orb component API

Orb is the main orb-ui component. It can run in controlled mode with a directional signal, or through a provider adapter.

import { Orb } from 'orb-ui'
;<Orb signal={{ state: 'listening', inputVolume: 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.
`adapter`	`OrbAdapter`	none	Provider adapter that subscribes to normalized signal updates.
`theme`	`OrbTheme`	`debug`	Theme name or typed preset/override object.
`size`	`number`	`200`	Component size in pixels.
`className`	`string`	none	Optional class name for the rendered theme.
`style`	`OrbStyle`	none	Root styles and typed `--orb-ui-*` design variables.
`slotProps`	`OrbSlotProps`	none	Classes, styles, and attributes for stable built-in theme slots.
`components`	`OrbThemeComponents`	none	Replacement radial control icon and connecting indicator.
`renderTheme`	`OrbThemeRenderer`	none	Fully custom artwork with normalized signal and lifecycle props.
`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 OrbThemeName = 'debug' | 'circle' | 'bars' | 'cloud' | 'radial'
type OrbThemePreset = 'balanced' | 'calm' | 'expressive'
type OrbTheme = OrbThemeName | OrbThemeConfig

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.

A string uses the theme’s balanced preset. To select another preset or change low-level values, pass { name, preset, appearance, geometry, motion }. Override fields are specific to the selected theme and fully typed.

<Orb
  signal={signal}
  theme={{
    name: 'circle',
    preset: 'calm',
    appearance: { colors: { speaking: '#f8f0ff' } },
    motion: { activityRiseMs: 90, activityFallMs: 220 },
  }}
/>

See theme customization for preset semantics and every low-level field. Application-wide visual defaults can be supplied without changing adapter ownership:

import { OrbThemeProvider, defineOrbTheme } from 'orb-ui'

const theme = defineOrbTheme({
  name: 'circle',
  preset: 'calm',
  appearance: { colors: { speaking: '#f472b6' } },
})

;<OrbThemeProvider theme={theme} size={260}>
  <Orb adapter={primaryAdapter} />
  <Orb adapter={secondaryAdapter} />
</OrbThemeProvider>

For responsive layout, set --orb-ui-size; for stable internal styling, use slotProps; for complete artwork ownership, use renderTheme. All three retain Orb’s normalized signal contract. See theme customization, stable slots, and custom renderers. 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
  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 }} />

inputVolume and outputVolume are stable normalized speech envelopes from 0 to 1. Orb reads input while state is listening, output while state is speaking, and zero in other states. See volume calibration for the provider mapping contract.

Migrating from `volume`

The ambiguous volume prop and OrbSignal.volume field have been removed. Put the value on the direction that owns it:

// Before
<Orb state="speaking" volume={level} />

// After
<Orb signal={{ state: 'speaking', outputVolume: level }} />

For a custom adapter, emit inputVolume for microphone activity and outputVolume for assistant playback. Provider adapters already do this and ship with directional calibration defaults.

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 from `volume`

Migrating callback-object adapters

​Props

​States

​Themes

​Adapter interface

​Migrating from volume

​Migrating callback-object adapters

​Related

Props

States

Themes

Adapter interface

Migrating from `volume`

Migrating callback-object adapters

Related