# Voice Input

Talk instead of typing: idle, listening with a live waveform and transcript, then transcribing.

- Category: AI & Agents
- Page: https://wunderui.com/components/voice-input
- Tier: Core and Pro

## Install

Voice Input ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { VoiceInput } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { VoiceInput } from "@wunderui/react"

export function Dictation() {
  const [state, setState] = useState<"idle" | "listening" | "transcribing">("idle")
  return (
    <VoiceInput
      state={state}
      seconds={7}
      onStart={() => setState("listening")}
      onStop={() => setState("transcribing")}
    />
  )
}
```

Expected result: A pill with an indigo microphone button and Tap to talk. Press it for a red stop button with a waveform and clock, then again for a spinner and Transcribing…, while recording itself is yours to add.

## When to use

### Use Voice Input for

- Dictating a message or a prompt instead of typing it
- A composer or form where the result is text that a person reads before sending
- A voice option next to a text field, never instead of it

### Use something else

- [Prompt Input](https://wunderui.com/components/prompt-input) for a typed prompt with attachments, a model picker and send
- [Textarea](https://wunderui.com/components/textarea) for plain multi-line text without voice
- [Drop Zone](https://wunderui.com/components/drop-zone) for an audio file that was recorded earlier

## Keyboard

The pill has one control, a native button, so the browser provides focus and activation.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the record button and away from it. It is the only focusable part, and it stays focusable while transcribing. |
| `Enter` or `Space` | Calls `onStart` when the pill is idle and `onStop` when it is listening. While it is transcribing nothing happens and the focus stays on the button. |

The pill has no shortcut of its own: no Escape to cancel, no push-to-talk. Add them where you hold the recording state, as the composer example does.

## Behavior

What the pill does with state, text, assistive technology and motion.

- **Controlled by you:** The state is idle, listening or transcribing, and you set it. The pill never records, asks for permission or changes state itself, and the start and stop handlers only tell you the button was pressed.
- **What the pill cannot say:** Asking for permission, a blocked microphone, no browser support and a silent recording have no state. Show them with the hint and a status line, and leave the pill out where voice can't work.
- **One button in every state:** The record button is the same element in all three states, so focus stays on it when recording stops. Its name changes, and while transcribing it is aria-disabled, not removed.
- **Live text:** The transcript is a polite live region and is read as it changes. The pill doesn't announce state changes, so add a status line (Listening, Transcribing, Done) that is in the page before it has text.
- **Clock and length:** While listening the clock shows the seconds as M:SS (0:07, 1:05, 12:30) with no hour, so 3,725 seconds read 62:05. While transcribing the pill says 7 seconds of audio, or 1 second.
- **Transcript and hint:** The transcript is one line, and long text is cut with an ellipsis while the live region still carries all of it. The hint only shows while idle and wraps, so keep it short.
- **Width:** The pill fills its container up to 360 px. Remove the maximum width with a class to let it fill a wider composer.
- **Motion:** The eighteen waveform bars pulse in a staggered loop, and the button colour fades quickly. A change of state swaps the content at once.
- **Reduced motion:** With reduced motion the bars stand still. The clock, the transcript and the red stop button, which also carries the state, are unaffected.

## Anatomy

- `VoiceInput`: A pill, 360 px wide at most, with a 1 px border and full radius. The border turns indigo while it listens, and it shows the state you give it and never opens the microphone.
- `Record button`: One native button of 36 px in every state, named Start recording, Stop recording or Transcribing. Idle it is an indigo microphone, listening a red stop square, transcribing an inert spinner.
- `Waveform`: Eighteen thin bars, only while listening. They are decorative with a fixed pattern: they pulse and don't follow the sound.
- `Transcript`: The words heard so far, on one line under the waveform, cut with an ellipsis. It is a polite live region.
- `Clock`: The elapsed time as M:SS in red tabular figures, only while listening.
- `Status text`: Replaces the waveform and transcript while idle and transcribing: Tap to talk with your hint, or Transcribing… with the length of the audio.

## Best practices

### When to use

- Use it when speaking is an option next to typing and the result is text a person reads before it is used. For typed prompts use Prompt Input, and for a plain text field use Textarea.

### Do

- Open the microphone only after a tap, never on page load. Request access in the start handler and handle the answer: the person may say no, or the device may have no microphone.
- Say what the pill can't: asking permission, a blocked microphone, no browser support, a recording with no speech. Put that in the hint and a status line, and skip the pill where voice can't work.
- Guard the start handler. The pill calls it on every tap while idle, even while the browser still asks for permission, so ignore a second tap until you know the answer.
- Pass the seconds from a measured timer and keep the state in your code. The pill only shows what it is given.
- Put the transcription into an editable field and move focus there. Let people read and correct it before anything is sent.
- Replace the default hint. The built-in line is neutral (Your words appear as text).

### Don't

- Don't send the transcription on its own. A recognised sentence can be wrong in a way that matters.
- Don't treat the waveform as a level meter, since the bars follow a fixed pattern, not the sound. If people need to see the microphone hears them, draw a real level.
- Don't update the transcript for every letter. The live region reads each change aloud, so send a word or a phrase at a time.

## API reference

### VoiceInput

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string |  | Extra classes for the pill. It is `w-full max-w-[360px]`; pass `max-w-none` to fill a wider container. |
| hint | React.ReactNode | "Your words appear as text" | The line under `Tap to talk`, shown only while idle. The default is `Your words appear as text`; replace it with a line of your own. `listeningHint` fills the line while listening before the first words arrive, and `onCancel` runs on Escape. |
| listeningHint | React.ReactNode |  | The line shown while listening and no words were heard yet, for example "Tap to stop, Esc to cancel". |
| onCancel | () => void |  | Called when Escape is pressed while listening and focus is inside the control. Escape discards the recording. |
| onStart | () => void |  | Called when the button is pressed while the pill is idle, also while you wait for permission: guard it. |
| onStop | () => void |  | Called when the button is pressed while the pill is listening. |
| seconds | number | 0 | The length of the recording in whole seconds. Default `0`. Listening shows it as `M:SS`; transcribing says `N seconds of audio`. |
| state | "idle" \| "listening" \| "transcribing" | "idle" | `idle`, `listening` or `transcribing`. Default `idle`. Picks the button, the text and the border. |
| transcript | React.ReactNode |  | The words heard so far, shown on one line while listening in a polite live region. Ignored in the other states. |

## Examples

### Microphone access: what the app says when the pill cannot start

### Transcript: the words heard so far

### Length: the clock and the length of the audio

### Hint: the line under Tap to talk

### Listening hint and Escape to cancel

## In context

### Dictation into a message box: permission, listening, transcribing and every way it fails

Press the button. The page simulates the microphone with timers and never opens yours; pick a scenario under the card: allowed, blocked, no browser support, or a recording with no speech.

### Voice or text in a composer: the pill takes the place of the field

The microphone button swaps the field for the pill and moves focus to the stop button. Enter or Space stops and Escape throws the recording away; afterwards the field returns with the words in it.

## For AI agents

`get_component("voice-input")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
