# Dictation Button

> A microphone button whose bars follow your voice, to toggle or hold to talk.

```tsx
'use client';

import { useState } from 'react';
import { DictationButton } from '@brand-studio/ui';

export default function DictationButtonDemo() {
  const [level, setLevel] = useState(0);
  return (
    <div style={{ display: 'grid', gap: 20, justifyItems: 'center' }}>
      <div style={{ display: 'flex', gap: 32, alignItems: 'center' }}>
        <div style={{ display: 'grid', gap: 8, justifyItems: 'center', fontSize: 14 }}><DictationButton onLevel={setLevel} />Click to toggle</div>
        <div style={{ display: 'grid', gap: 8, justifyItems: 'center', fontSize: 14 }}><DictationButton mode="hold" onLevel={setLevel} />Hold to talk</div>
      </div>
      <p style={{ margin: 0, color: 'var(--bs-muted)', fontSize: 14, fontVariantNumeric: 'tabular-nums' }}>Level {Math.round(level * 100)}%</p>
    </div>
  );
}
```

## Installation

```sh
npm install @brand-studio/ui
```

React 18 or 19 is a peer dependency. Import the stylesheet once and wrap the app in a brand theme:

```tsx
import '@brand-studio/ui/styles.css';
import { BrandTheme, DictationButton } from '@brand-studio/ui';
import brand from './brand.json';

<BrandTheme palette={brand.tokens} mode="system">
  {/* your app */}
</BrandTheme>
```

## Usage

```tsx
import { DictationButton } from '@brand-studio/ui';
```

```tsx
<DictationButton onListeningChange={setListening} onLevel={setLevel} />
<DictationButton mode="hold" />
```

The first press asks for the microphone. While on, five bars follow your voice and `onLevel` reports the loudness from 0 to 1. `mode="hold"` listens only while the button, Space or Enter is held down.

The button only captures sound. Send it to your own speech recognition, and show the words with LiveTranscript. The microphone needs a secure page (https or localhost).

## Accessibility

- The button reports whether it is pressed, and its label stays the same in both states.
- If the browser blocks the microphone, the button turns off and says "Microphone blocked" in words.

## API Reference

| Prop | Type | Default |
|---|---|---|
| `listening?` | `boolean` | – |
| `onListeningChange?` | `((listening: boolean) => void)` | – |
| `onLevel?` | `((level: number) => void)` | – |
| `mode?` | `"hold" \| "toggle"` | `'toggle'` |
| `label?` | `string` | – |
| `blockedLabel?` | `string` | `'Microphone blocked'` |
| `className?` | `string` | `''` |

Source: https://brandstudio.js.org/docs/components/dictation-button/
