# Voice button

A React component in [Beamline](https://beamline.io/)'s [Voice & audio](https://beamline.io/components/voice) category. Live demo: https://beamline.io/components/voice-button

The control that starts and stops talking: click to toggle or hold to talk (pointer, Space, Enter or a global shortcut), with a live level while recording, a loader while words are finished, and a check or a retry when it ends. The state comes from your operation, never from a timer.

## Use it for

- Starting and stopping dictation, a voice command or a voice note.
- Push-to-talk with a keyboard shortcut.

## Not for

- Ordinary actions ([button](https://beamline.io/components/button)).
- A whole voice call with mute and text ([conversation-bar](https://beamline.io/components/conversation-bar)).
- A text field you dictate into ([speech-input](https://beamline.io/components/speech-input), which uses this).

## Anatomy

- button
- icon (mic, check, alert)
- label
- live level (while recording)
- shortcut keycaps
- glow (optional)

## Variants

- **variant**: secondary, outline, ghost, primary, accent
- **size**: sm, md, lg
- **mode**: toggle, hold

## States

- idle
- recording (pressed, a red ring drawn over the look's own paint, red mic, live level, optional glow)
- processing (loader, keeps size and focus)
- success (green check and the word)
- error (red alert icon and a retry label; icon-only keeps a red mic)
- disabled

## Keyboard

- Enter / Space: toggle (toggle mode) or hold to talk (hold mode)
- The `shortcut` works anywhere on the page while the button is mounted (not inside text fields unless it has a modifier); in hold mode releasing the key stops

## Motion

The level moves only while recording; the glow fades in over --pui-motion-in and out over --pui-motion-out and runs nothing when idle. Labels change with the system Button's morph.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `"idle" \| "recording" \| "processing" \| "success" \| "error"` | `"idle"` | Driven by your operation (useSpeechToText's status maps onto it). |
| `onPress` | `() => void` | — | Toggle mode: each click or shortcut press. |
| `onPressStart / onPressEnd` | `() => void` | — | Hold mode: pressed down / let go. |
| `mode` | `"toggle" \| "hold"` | `"toggle"` |  |
| `shortcut` | `string[]` | — | Keys as Kbd takes them, e.g. ["alt", "space"] or ["mod", "shift", "v"]. |
| `source` | `MediaStream \| LevelSource \| (() => number)` | — | The level drawn while recording. |
| `label` | `ReactNode` | — | Visible text; defaults follow the state (Dictate, Listening, Finishing, Added, Try again). With iconOnly it becomes the accessible name. |
| `iconOnly` | `boolean` | — |  |
| `glow` | `boolean` | — | Colour pools under the button while recording. |
| `variant / size / disabled` | `ButtonVariant / "sm" \| "md" \| "lg" / boolean` | — |  |
| `classNames` | `VoiceButtonClassNames` | — |  |
| `style / ref` | `CSSProperties / native Ref` | — |  |

## Built from

- button
- [live-waveform](https://beamline.io/components/live-waveform)
- kbd
- glow
- spinner

## Dependencies

`lucide-react`

## Import

```tsx
import { VoiceButton } from "@/components/voice-button/voice-button";
```

## Get it

Voice button is part of Beamline: 190 React components and screens your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 one payment (regular $200), no subscription, a year of updates, one licence for your whole team. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Voice & audio

- [Audio player](https://beamline.io/components/audio-player): One audio element and its controls: play with a loading state, a scrub bar with time, skip, speed and a playlist whose rows play into the same player…
- [Bar visualizer](https://beamline.io/components/bar-visualizer): A row of bars that says what a voice agent is doing: a sweep while connecting, the person's voice while listening, a slow breath while thinking, the…
- [Conversation bar](https://beamline.io/components/conversation-bar): The control bar of a voice call with an agent: one button to call and hang up, the agent's state as bars, a call timer, mute, and typing when talking is…
- [Live waveform](https://beamline.io/components/live-waveform): Loudness drawn as it happens: a scrolling history of the microphone (or any live source) or its spectrum, a calm processing state while words are…
- [Matrix](https://beamline.io/components/matrix): A dot-matrix display: animated frame sets (loading, pulse, wave, syncing), text and digits in a 5×7 font, or a VU meter of levels or a live source. One…
- [Microphone selector](https://beamline.io/components/mic-selector): Choose the microphone, test it with a live level and mute it, with every permission and device state spelled out: not yet allowed, blocked (and how to…
- [Orb](https://beamline.io/components/orb): The agent's presence: a thin ring of light around a lens in the brand's hue that holds still at rest, sends an arc round while thinking and widens with…
- [Scrub bar](https://beamline.io/components/scrub-bar): A seekable timeline for audio or video: elapsed and total time, what has loaded, chapter marks, a time preview under the pointer, and the full keyboard…
- [Speech input](https://beamline.io/components/speech-input): A text field you can speak into: the mic dictates through any speech-to-text provider, the phrase being heard shows apart from the finished words, and…
- [Transcript viewer](https://beamline.io/components/transcript-viewer): A recording and its words together: the spoken word lights up as it plays and the transcript follows it, any word or paragraph time plays from there…
- [Voice picker](https://beamline.io/components/voice-picker): Choose a text-to-speech voice from a searchable list (name, accent, tone, use) and hear it first: each voice has its own orb, previews play one at a time…
- [Waveform](https://beamline.io/components/waveform): The shape of a recording: one bar per slice of loudness, fitted to any width, with the played part in the accent, unmeasured slices hatched and a loading…