Voice button

A React component in Beamline's Voice & audio category.

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).
A whole voice call with mute and text (conversation-bar).
A text field you dictate into (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
kbd
glow
spinner

Dependencies

lucide-react

Import

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 · Connect your agent