Skip to content
WunderUI

Voice Input

Pro

A pill for dictation: tap to talk, listen with a live waveform and the words heard so far, then wait for the text.

Playground

Tap to talkSpeak, then check the text

Installation

Voice Input comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

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

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 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.

Tap to talkSpeak, then check the text

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.

Rename the Tabs props to match the new naming0:07

Length

The clock counts the seconds you pass, as minutes and seconds. While transcribing, the pill says how much audio it is working on.

Rename the Tabs props to match the new naming0:07

Hint

Replace the built-in line with one of your own. It shows only while the pill is idle.

Tap to talkYour words appear as text

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

Tap to stop, Esc to cancel0:04

Keyboard interactions

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

TaborShiftTab
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.

Rename the Tabs props to match the new naming0:07
  • data-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.

  • 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.

  • Optional

    Eighteen thin bars, only while listening. They are decorative with a fixed pattern: they pulse and don't follow the sound.

  • Optional

    The words heard so far, on one line under the waveform, cut with an ellipsis. It is a polite live region.

  • Optional

    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.

PropTypeDefaultDescription
state"idle" | "listening" | "transcribing""idle", or . Default . Picks the button, the text and the border.
transcriptReactNode—The words heard so far, shown on one line while listening in a polite live region. Ignored in the other states.
secondsnumber0The 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.
hintReactNode"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.
classNamestring—Extra classes for the pill. It is ; pass to fill a wider container.
listeningHintReactNode—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.

MCPget_component("voice-input")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.