> ## Documentation Index
> Fetch the complete documentation index at: https://orb-ui.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Orb component API

> Reference for the Orb component props, states, themes, and adapter interface.

`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.

```tsx theme={null}
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

```ts theme={null}
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

```ts theme={null}
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:

```tsx theme={null}
<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.

```tsx theme={null}
<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

```ts theme={null}
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.

```tsx theme={null}
<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.

```ts theme={null}
// 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.

## Related

* [Themes and states](/docs/themes/voice-states)
* [Custom integrations](/docs/adapters/custom)
* [Signal-based adapter architecture](/docs/guides/signal-based-voice-agent-ui)
* [Vapi adapter](/docs/adapters/vapi)