# Voice orb

A shadcn/ui block for voice AI apps: a rim-lit ball of points that listens, thinks, speaks and plays music, with a talk button and a live mic option.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available for the docs, pricing and about pages: append `.md` to the URL or send an `Accept: text/markdown` header (the home page answers the header too). An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

## At a glance

- **Good for:** Voice assistants and AI voice chat screens; Voice mode in AI chat apps; Call, dictation and voice note recorders; Landing pages for voice AI products
- **Category:** AI · **Type:** Cards · **Style:** Motion, Minimal, Dark mode
- **See it:** [Live preview](https://www.craftui.space/docs/blocks/voice-orb) · [Video](https://pub-52b0d9cec7c64f638ba3f33a29718fa6.r2.dev/Videos_product_cards/cards-voice-orb.7d615ef7.mp4)

## Install

```bash
pnpm dlx shadcn@latest add https://www.craftui.space/r/voice-orb.json
```

This is a paid item (BLK-K6XZ1A): the install needs a craftUI plan or a purchase of it. Signed in, the docs page gives your personal install command. Plans: https://www.craftui.space/pricing

## Usage

```tsx
import VoiceOrb from "@/components/blocks/voice-orb/voice-orb";

export default function Page() {
  return <VoiceOrb />;
}
```

With no props it renders with demo content; pass your own through the props below.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `VoiceState` | — | What the assistant is doing. Leave it out for the built-in demo, which runs one conversation when the button is pressed. |
| `level` | `VoiceLevel` | — | Voice level 0–1, or a function read every frame (see `useMicLevel`). |
| `label` | `string` | — | The text in the middle. Defaults to the state's own word. |
| `eyebrow` | `string` | — | A small line above the label, e.g. "Now playing". |
| `onToggle` | `() => void` | — | Called when the talk button is pressed (controlled use). |
| `buttonLabel` | `string` | — | The talk button's accessible name. Defaults by state. |
| `showControls` | `boolean` | `true` | Show the talk button (and, in the demo, the mic toggle). Turn it off when your own UI drives `state`. Defaults to true. |

It also accepts every `<div>` attribute (`className`, `id`, `aria-*` and so on).

## Files

The install adds:

- `components/blocks/voice-orb/voice-orb.tsx`
- `components/blocks/voice-orb/voice-orb-gl.ts`

npm dependencies (installed for you): `motion`, `torph`.

shadcn/ui components it uses (the shadcn CLI adds any that are missing): `button`.