Skip to content
caliper ui docs
DemoSign inGet Pro

Pro

Dictation pill

A microphone button for a chat composer that springs open into a recording pill with cancel, a live waveform, a running time and insert. Inserting shows a moment of transcribing, then the pill folds back and the text arrives.

Pro
pnpm dlx shadcn@latest add @caliper/dictation-pill

Message

Press the microphone and speak.

Installs components/ui/dictation-pill.tsxDepends on lucide-reactMotion honours reduced motion

When to use

Use it for

  • Chat and AI composers, note-taking and search fields.
  • Mobile-first forms where speaking is faster than typing.

Skip it when

  • Long recordings to keep; use `VoiceRecorder`.
  • Voice conversations; use `VoiceAgent`.

Decisions

Why it is built this way, so you know what to keep when you change your copy.

Behaviour

Grows from the button
The pill opens from the mic's own circle with a slight overshoot and closes back into it, so the composer never jumps.
Your voice, live
The bars come from the microphone's level, newest on the right; simulate draws a made-up level for demos.

Usage

Errors in place
A blocked microphone or failed transcription is said in the pill, which then closes; Escape cancels and Enter inserts.

Installation

terminal
pnpm dlx shadcn@latest add @caliper/dictation-pill

Adds its 2 files to components/ui/, each with its own stylesheet, and installs their packages. Pro installs with your access token, set up once per project. See Pro access. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage

Import it from your copy of the source. The example behind the preview comes with the source.

example.tsx
import { DictationPill } from "@/components/ui/dictation-pill"

The worked example comes with Pro

The 34-line example behind the preview opens here, ready to copy.

  • 602 Pro parts, blocks and page templates, all with source
  • $199 once, with a year of updates. What you have stays yours
  • A full refund within 14 days if it is not for you
Checking your licence…

API reference

DictationPill

component

Also accepts the native props of its root element and a ref.

PropTypeDefaultDescription
onTranscribe *(audio: Blob | null) => Promise<string>—Turns the recording into text. Gets null when `simulate` is on.
onInsert *(text: string) => void—Receives the text to put in the composer.
simulatebooleanfalseDraws a made-up level instead of asking for the microphone, for demos and tests.
maxSecondsnumber120Stops recording on its own after this many seconds.

Accessibility

It exposes group, status and alert semantics, with aria-label and aria-hidden kept in step with state. Changes that matter are announced through a live region.

KeyBehaviour
EscapeCloses or cancels, then returns focus to where it came from.
EnterActivates the focused control.

Motion

It checks prefers-reduced-motion itself and settles immediately instead of travelling. Every state is still reachable.

All Media examples