@dictate-button/react

React text field components with speech-to-text dictation powered by 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

pnpm add @dictate-button/react

Registration Required

You need to register your app on dictate-button.io to use the @dictate-button/react components in your app.

To do that, visit dash.dictate-button.io, 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

import { DictateInput, DictateTextarea, DictateButton } from '@dictate-button/react';

function MyForm() {
  return (
    <div>
      <DictateInput
        type="text"
        placeholder="Start typing or click the mic..."
        className="your-input-class"
      />

      <DictateTextarea
        rows={5}
        placeholder="Or speak here..."
        className="your-textarea-class"
      />

      <DictateButton
        onDictateEnd={(text) => console.log('Transcribed:', text)}
      />
    </div>
  );
}

Why This Integration Layer?

The 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

<DictateInput />

A text input with integrated speech-to-text button.

<DictateInput
  type="text"
  placeholder="Type or speak..."
  buttonSize={30}
  onDictateEnd={(text) => console.log(text)}
/>

<DictateTextarea />

A textarea with integrated speech-to-text button.

<DictateTextarea
  rows={5}
  placeholder="Type or speak..."
  buttonSize={30}
  onDictateEnd={(text) => console.log(text)}
/>

<DictateButton />

A standalone dictate button for custom event-based implementations.

<DictateButton
  size={30}
  onDictateStart={() => 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:

import { useRef } from 'react';
import { DictateButton, useDictateButtonEventHandlers } from '@dictate-button/react';

function CustomInput() {
  const inputRef = useRef<HTMLInputElement>(null);
  const handlers = useDictateButtonEventHandlers(inputRef);

  return (
    <div style={{ position: 'relative' }}>
      <input ref={inputRef} style={{ paddingRight: '40px' }} />
      <DictateButton
        {...handlers}
        style={{ position: 'absolute', right: '4px', top: '50%', transform: 'translateY(-50%)' }}
      />
    </div>
  );
}

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:

import { DictateInput } from '@dictate-button/react';
import { cn } from '@/lib/utils'; // clsx + tailwind-merge utility

<DictateInput
  className={cn(
    "flex h-10 w-full rounded-md border border-input bg-background px-3 py-2",
    "text-sm ring-offset-background",
    "placeholder:text-muted-foreground",
    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
    "disabled:cursor-not-allowed disabled:opacity-50"
  )}
/>

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

import type {
  DictateButtonComponentProps,
  DictateInputProps,
  DictateTextareaProps,
  UseDictateButtonEventHandlersReturn,
} from '@dictate-button/react';

Development

# Build the library
pnpm build

# Run tests
pnpm test

# Type checking
pnpm typecheck

# Watch mode for development
pnpm dev

License

Apache-2.0

Credits

Built on top of dictate-button by the Dictate Button team.