https://github.com/dictate-button/dictate-button-react
React text fields with Dictate Button integrated
https://github.com/dictate-button/dictate-button-react
dictate dictate-button react speech-to-text voice-recognition
Last synced: 4 months ago
JSON representation
React text fields with Dictate Button integrated
- Host: GitHub
- URL: https://github.com/dictate-button/dictate-button-react
- Owner: dictate-button
- Created: 2026-01-20T10:57:12.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-28T12:10:36.000Z (4 months ago)
- Last Synced: 2026-02-28T15:15:26.102Z (4 months ago)
- Topics: dictate, dictate-button, react, speech-to-text, voice-recognition
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@dictate-button/react
- Size: 152 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# @dictate-button/react
[](https://www.npmjs.com/package/@dictate-button/react)
[](https://github.com/dictate-button/dictate-button-react/actions/workflows/ci.yml)
React text field components with speech-to-text dictation powered by [Dictate Button](https://github.com/dictate-button/dictate-button).
Provides a thin integration layer that avoids DOM scanning and mutation, making it fully compatible with React and any CSS framework.
## Features
- **No DOM Scanning**: Declarative React components instead of inject scripts
- **No DOM Mutation**: Integrates naturally with React's virtual DOM
- **Framework Agnostic**: Works with any CSS framework (Tailwind, Bootstrap, etc.)
- **TypeScript First**: Full type safety and IntelliSense support
- **React 19 Ready**: Built for modern React
- **Controlled & Uncontrolled**: Supports both patterns
- **Customizable**: Full control over styling and behavior
## Installation
```bash
pnpm add @dictate-button/react
```
## Registration Required
**You need to register your app on [dictate-button.io](https://dictate-button.io) to use the `@dictate-button/react` components in your app.**
To do that, visit [dash.dictate-button.io](https://dash.dictate-button.io/auth/register), create a free account and register your site.
No API key configuration needed - the service works automatically once your site is registered and verified.
## Quick Start
```tsx
import { DictateInput, DictateTextarea, DictateButton } from '@dictate-button/react';
function MyForm() {
return (
console.log('Transcribed:', text)}
/>
);
}
```
## Why This Integration Layer?
The [dictate-button](https://github.com/dictate-button/dictate-button) package includes inject scripts that scan the DOM using `querySelectorAll` and mutate it by wrapping elements.
This integration layer provides:
- ✅ Declarative React components
- ✅ No DOM scanning or mutation
- ✅ Works with any CSS framework or styling approach
- ✅ Full TypeScript support
- ✅ React refs, controlled components, and hooks
## Components
### ``
A text input with integrated speech-to-text button.
```tsx
console.log(text)}
/>
```
### ``
A textarea with integrated speech-to-text button.
```tsx
console.log(text)}
/>
```
### ``
A standalone dictate button for custom event-based implementations.
```tsx
console.log('Started')}
onDictateText={(text) => console.log('Interim:', text)}
onDictateEnd={(text) => console.log('Final:', text)}
onDictateError={(error) => console.error(error)}
/>
```
Use this when you want to handle dictation events yourself without automatic text field integration.
### `useDictateButtonEventHandlers` Hook
For building custom text field integrations, use the hook to get text insertion event handlers:
```tsx
import { useRef } from 'react';
import { DictateButton, useDictateButtonEventHandlers } from '@dictate-button/react';
function CustomInput() {
const inputRef = useRef(null);
const handlers = useDictateButtonEventHandlers(inputRef);
return (
);
}
```
## Props
### DictateInput & DictateTextarea Props
All standard HTML input/textarea props are supported, plus:
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `buttonSize` | `number` | `30` | Size of the dictate button in pixels |
| `buttonClassName` | `string` | - | CSS class for the button |
| `apiEndpoint` | `string` | - | Custom API endpoint for transcription |
| `language` | `string` | `'en'` | Language code (e.g., 'en', 'es', 'fr') |
| `theme` | `'light' \| 'dark'` | - | Button theme |
| `onDictateStart` | `() => void` | - | Called when dictation starts (overrides text insertion if provided) |
| `onDictateText` | `(text: string) => void` | - | Called with interim results (overrides text insertion if provided) |
| `onDictateEnd` | `(text: string) => void` | - | Called with final transcription (overrides text insertion if provided) |
| `onDictateError` | `(error: Error \| string) => void` | - | Called on errors (overrides text insertion if provided) |
### DictateButton Props
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `number` | `30` | Size of the button in pixels |
| `className` | `string` | - | CSS class for the button |
| `style` | `React.CSSProperties` | - | Inline styles for the button |
| `apiEndpoint` | `string` | - | Custom API endpoint for transcription |
| `language` | `string` | `'en'` | Language code (e.g., 'en', 'es', 'fr') |
| `theme` | `'light' \| 'dark'` | - | Button theme |
| `onDictateStart` | `() => void` | - | Called when dictation starts |
| `onDictateText` | `(text: string) => void` | - | Called with interim results |
| `onDictateEnd` | `(text: string) => void` | - | Called with final transcription |
| `onDictateError` | `(error: Error \| string) => void` | - | Called on errors |
## Styling with Tailwind CSS
These components accept standard `className` props and work with any CSS framework. Here's an example using Tailwind CSS with the popular `cn()` utility for conditional classes:
```tsx
import { DictateInput } from '@dictate-button/react';
import { cn } from '@/lib/utils'; // clsx + tailwind-merge utility
```
The `cn()` utility is commonly used in Tailwind projects to merge class names. It's not specific to any component library.
## Examples
See [EXAMPLES.md](./EXAMPLES.md) for comprehensive usage examples including:
- Basic usage
- Tailwind CSS styling
- Controlled components
- Custom event handlers
- React Hook Form integration
- Advanced hook usage
## TypeScript
All components and hooks are fully typed. Import types as needed:
```tsx
import type {
DictateButtonComponentProps,
DictateInputProps,
DictateTextareaProps,
UseDictateButtonEventHandlersReturn,
} from '@dictate-button/react';
```
## Development
```bash
# Build the library
pnpm build
# Run tests
pnpm test
# Type checking
pnpm typecheck
# Lint and format check (Biome)
pnpm check
# Auto-fix formatting
pnpm format
# Lint only
pnpm lint
# Watch mode for development
pnpm dev
```
## License
Apache-2.0
## Credits
Built on top of [dictate-button](https://github.com/dictate-button/dictate-button) by the Dictate Button team.