Voice Input
ProA pill for dictation: tap to talk, listen with a live waveform and the words heard so far, then wait for the text.
Playground
Installation
Voice Input comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import { VoiceInput } from "@wunderui/react"Then use it:
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 for
- Prompt Input for a typed prompt with attachments, a model picker and send
- Textarea for plain multi-line text without voice
- Drop Zone for an audio file that was recorded earlier
Microphone access
The pill knows idle, listening and transcribing. Asking for permission, a blocked microphone, a browser without one and a silent recording are yours to explain, in the hint and in a status line.
Waiting for microphone permission.
Microphone access is blocked. Allow it in the site settings of your browser, or type instead.
Voice input is not available in this browser. Type your message instead.
No speech was heard. Check your microphone and try again.
Transcript
While listening the pill shows the words heard so far on one line. A long text is cut with an ellipsis, but the live region still reads all of it.
Length
The clock counts the seconds you pass, as minutes and seconds. While transcribing, the pill says how much audio it is working on.
Hint
Replace the built-in line with one of your own. It shows only while the pill is idle.
Newer props
listeningHint fills the line before the first words arrive, and onCancel runs when Escape is pressed while the control has focus. The idle hint has a neutral default text.
Listening hint and Escape to cancel
Keyboard interactions
The pill has one control, a native button, so the browser provides focus and activation.
- TaborShift+Tab
- Moves focus to the record button and away from it. It is the only focusable part, and it stays focusable while transcribing.
- EnterorSpace
- Calls when the pill is idle and 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 and motion
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
The figure marks the listening state. While idle or transcribing, the status text replaces the waveform, transcript and clock.
- 1data-slot="voice-input"
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.
- 2
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.
- 3Optional
Eighteen thin bars, only while listening. They are decorative with a fixed pattern: they pulse and don't follow the sound.
- 4Optional
The words heard so far, on one line under the waveform, cut with an ellipsis. It is a polite live region.
- 5Optional
The elapsed time as M:SS in red tabular figures, only while listening.
- Optional
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
- 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.
- Do
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.
- Do
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.
- Do
Pass the seconds from a measured timer and keep the state in your code. The pill only shows what it is given.
- Do
Put the transcription into an editable field and move focus there. Let people read and correct it before anything is sent.
- Do
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
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
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 is a plain component, not a wrapper of a primitive, so this table lists every prop.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| state | "idle" | "listening" | "transcribing" | "idle" | , or . Default . Picks the button, the text and the border. |
| transcript | ReactNode | — | The words heard so far, shown on one line while listening in a polite live region. Ignored in the other states. |
| seconds | number | 0 | The length of the recording in whole seconds. Default . Listening shows it as ; transcribing says . |
| 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. |
| hint | ReactNode | "Your words appear as text" | The line under , shown only while idle. The default is ; replace it with a line of your own. fills the line while listening before the first words arrive, and runs on Escape. |
| className | string | — | Extra classes for the pill. It is ; pass to fill a wider container. |
| listeningHint | 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. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("voice-input")The full library index for assistants is at /llms.txt.