# Voice orb

> A living orb for voice assistants: idle, listening, thinking and speaking states.

Component · Pro · https://lodeui.com/components/voice-orb

## When to use

- Voice assistants and call screens.

## When not to use

- Text chat: use a typing indicator.

## Installation

```bash
npx shadcn@latest add @lode/voice-orb
```

Pro: needs a Lode API key and the `@lode` registry in components.json. See https://lodeui.com/docs/cli.

npm dependencies: motion

## Usage

```tsx title="example.tsx"
import { VoiceOrb } from "@/components/ui/voice-orb";

<VoiceOrb state={state} level={micLevel} />
```

## API reference

### VoiceOrb

An animated orb that reflects the assistant's state.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| state | `"idle" \| "listening" \| "thinking" \| "speaking"` | – | Current state; announced. |
| level | `number` | `0` | 0–1 loudness for listening and speaking. |
| size / colors | `number / [string, string, string]` | `160` | Look. |

## Accessibility

- role="status" announces the state as text.

## Motion

- Idle breathes; listening and speaking swell with level; thinking swirls fast with a dashed ring.

## Responsive behavior

- Fixed size; scale with the size prop.

## Performance

- Two rotating gradients; drive level from an AnalyserNode at ~10–20 fps.

## Notes for AI

- Smooth the level before passing it in to avoid jitter.

## Related

- [Chat message](https://lodeui.com/components/chat-message) — A chat turn with streaming cursor, copy, feedback and regenerate.
- [Audio player](https://lodeui.com/components/audio-player) — Compact audio player with a clickable waveform, skip and playback speed.
- [Loader](https://lodeui.com/components/loader) — Six loading indicators (spinner, dots, bars, pulse, orbit, ring) with one API.