# Voice orb

> A sphere of drifting color lobes for voice modes: idle, listening, thinking and speaking each move differently, it swells with the audio level, and a halo pulses behind it.

- Type: Component (feedback)
- Access: Free, open source (MIT)
- Page: https://goodui.dev/native/components/voice-orb
- Markdown: https://goodui.dev/native/components/voice-orb.md
- Registry item: https://goodui.dev/native/r/voice-orb.json
- Dependencies: react-native-reanimated, react-native-svg
- Keywords: react native voice orb, ai voice mode, audio level visualizer, siri orb, listening animation

## When to use

- A voice conversation screen.
- A calm hero for an empty AI chat, at a small size in idle.

## When not to use

- Scrubbing or showing recorded audio: use a waveform.
- Plain loading states: use a spinner.

## Installation

With the shadcn CLI (needs a components.json in the Expo app), then `npx expo install --fix` so native dependencies match your Expo SDK. The foundation comes along the first time.

```bash
npx shadcn@latest add https://goodui.dev/native/r/voice-orb.json
npx expo install --fix
```

The component lands in `components/goodui-native/voice-orb/` and imports the foundation from `components/goodui-native/foundation/` with relative paths; it also installs locale.

Built-in strings follow `<GooduiLocaleProvider>` (one [language pack](https://goodui.dev/native/r/locale-tr.json) translates the whole kit); the `labels` prop overrides them for one instance.

## Usage

```tsx
import { VoiceOrb } from "@/components/goodui-native/voice-orb/voice-orb";

<VoiceOrb mode={speaking ? "speaking" : "listening"} size={210} />

// With a real recorder meter, in a shared value from 0 to 1:
<VoiceOrb mode="listening" level={meter} />
```

## API reference

### VoiceOrb

`import { VoiceOrb } from "@/components/goodui-native/voice-orb/voice-orb";`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` (required) | `"idle" \| "listening" \| "thinking" \| "speaking"` | – | – |
| `size` | `number` | `220` | Diameter in points. |
| `level` | `SharedValue<number>` | – | Your recorder's meter, 0 to 1. Without it the orb synthesizes a believable level on the UI thread. |
| `colors` | `[string, string]` | – | Hue pair of the orb. Defaults to the accent and its soft tint. |
| `paused` | `boolean` | `false` | Stops the frame callback, for an orb that is mounted but off screen. |
| `labels` | `Partial<VoiceOrbLabels>` | – | – |
| `style` | `StyleProp<ViewStyle>` | – | Style for the outer container. |
| `testID` | `string` | – | Identifier for end-to-end tests. |

## Accessibility

- Read as an image labeled with the mode, in a polite live region so mode changes are announced.

## Motion

- Each mode has its own spin speed and level curve, computed in one frame callback.
- Without `level` it synthesizes a level, so the motion is then not a real measure of the audio.
- Reduced motion: the lobes stop and the scale holds. A `level` you pass still shows as opacity.

## Performance

- One frame callback on the UI thread, with no React re-renders. Idle runs at a third of the frame rate, reduced motion stops it, and `paused` stops it for an orb that is mounted but off screen.

## Notes for AI

- Pass `level` from your recorder or player when you have one.
- The default colors come from the accent. Pass `colors` for a persona.
- The box is 1.45 times `size` so the halo has room.
- Show captions beside it: the orb does not carry what was said.

## Related

- [Prompt composer](https://goodui.dev/native/components/prompt-composer.md): The input for AI apps: a field that grows with the text on a spring, chips that add phrases to the prompt, and a send button that morphs into a stop square while a job runs.
- [Stream text](https://goodui.dev/native/components/stream-text.md): Text that arrives word by word: new words fade up and a caret pulses at the end, and when streaming stops it becomes one plain text block.
- [AI provider](https://goodui.dev/native/components/ai-provider.md): The logic layer behind the AI components, with no UI: a typed provider adapter with an offline mock, a credit ledger that keeps subscription and bought credits apart, and a generation queue that charges, refunds and retries.

## Guidance for AI tools

Voice orb: A sphere of drifting color lobes for voice modes: idle, listening, thinking and speaking each move differently, it swells with the audio level, and a halo pulses behind it. Use only the documented props. Keep accessibility, reduced motion and both color schemes intact when adapting it.

Full library index: https://goodui.dev/native/llms.txt