@syntropy-labs/react-web-speech

React hooks for the Web Speech API with first-class DX: mic permissions, listening states, browser compatibility, and cursor-aware text insertion.

Features

• 🎙️ Mic permission state management — Know if permission is prompt, granted, or denied
• 📝 Cursor-aware text insertion — Insert transcribed text at cursor position
• 🔇 Auto-silence detection — Automatically stop listening after silence
• 🔄 Auto-restart on network errors — Resilient to connection issues
• 🌐 Browser compatibility — Handles Chrome, Edge, Safari with proper prefixing
• 📦 Tree-shakeable — Only bundle what you use (~5KB gzipped)
• 🔷 TypeScript-first — Full type safety and IDE autocomplete
• ⚛️ React 17+ ready — Strict Mode compatible

Installation

npm install @syntropy-labs/react-web-speech
# or
yarn add @syntropy-labs/react-web-speech
# or
pnpm add @syntropy-labs/react-web-speech

Quick Start

import { useSpeechInput } from '@syntropy-labs/react-web-speech'

function VoiceInput() {
  const {
    transcript,
    isListening,
    isSupported,
    permissionState,
    start,
    stop,
    toggle,
  } = useSpeechInput({
    lang: 'en-US',
    continuous: false,
    silenceTimeout: 3000,
  })

  if (!isSupported) {
    return <p>Speech recognition is not supported in this browser.</p>
  }

  return (
    <div>
      <button onClick={toggle}>
        {isListening ? '🔴 Stop' : '🎙️ Start'}
      </button>
      <p>Permission: {permissionState}</p>
      <p>Transcript: {transcript}</p>
    </div>
  )
}

API Reference

useSpeechInput(options?)

The primary hook for speech-to-text functionality.

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | lang | string | navigator.language | Recognition language (e.g., 'en-US') | | continuous | boolean | false | Keep listening after pause | | interimResults | boolean | true | Show real-time partial results | | maxAlternatives | number | 1 | Max alternative transcriptions | | silenceTimeout | number | 3000 | Auto-stop after silence (ms), 0 to disable | | autoRestart | boolean | false | Auto-restart on network errors | | onResult | (text, isFinal) => void | - | Callback on speech result | | onError | (error) => void | - | Callback on error | | onStart | () => void | - | Callback when listening starts | | onEnd | () => void | - | Callback when listening ends |

Returns

| Property | Type | Description | |----------|------|-------------| | transcript | string | Final transcribed text | | interimTranscript | string | Real-time partial text | | isListening | boolean | Currently listening | | isSupported | boolean | Browser supports Speech API | | permissionState | 'prompt' \| 'granted' \| 'denied' \| 'unsupported' | Mic permission state | | error | SpeechError \| null | Error details | | start | () => Promise<void> | Start listening | | stop | () => void | Stop listening gracefully | | abort | () => void | Abort listening immediately | | toggle | () => Promise<void> | Toggle listening | | clear | () => void | Clear transcript and error | | requestPermission | () => Promise<MicPermissionState> | Request mic permission |

useSpeechInputWithCursor(options)

Extended hook that automatically inserts transcribed text at the cursor position.

import { useSpeechInputWithCursor } from '@syntropy-labs/react-web-speech'
import { useState, useRef } from 'react'

function VoiceTextarea() {
  const [value, setValue] = useState('')
  const inputRef = useRef<HTMLTextAreaElement>(null)

  const { isListening, toggle } = useSpeechInputWithCursor({
    inputRef,
    value,
    onChange: setValue,
    appendSpace: true, // Add space after inserted text
  })

  return (
    <div>
      <textarea ref={inputRef} value={value} onChange={(e) => setValue(e.target.value)} />
      <button onClick={toggle}>{isListening ? 'Stop' : 'Speak'}</button>
    </div>
  )
}

Additional Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | inputRef | RefObject<HTMLInputElement \| HTMLTextAreaElement> | required | Ref to the input element | | value | string | required | Current controlled value | | onChange | (value: string) => void | required | Value setter | | appendSpace | boolean | true | Add space after inserted text |

Additional Returns

| Property | Type | Description | |----------|------|-------------| | insertAtCursor | (text: string) => void | Manually insert text at cursor |

Cursor Utilities

Low-level utilities for cursor position management:

import { 
  supportsSelection,
  getCursorPosition,
  setCursorPosition,
  insertTextAtCursor 
} from '@syntropy-labs/react-web-speech'

// Check if input type supports cursor APIs
supportsSelection(inputElement) // true for text, search, tel, password, url

// Get current cursor position
const { start, end } = getCursorPosition(inputElement)

// Set cursor position (uses requestAnimationFrame for React compatibility)
setCursorPosition(inputElement, position, { focus: true })

// Insert text at cursor in controlled input
insertTextAtCursor(inputRef, 'hello', currentValue, setValue)

Note: email and number input types don't support cursor APIs. The utilities fall back to appending text at the end.

Browser Support

| Browser | Support | |---------|---------| | Chrome / Chromium | ✅ Full | | Edge | ✅ Full | | Safari 14.1+ | ⚠️ Partial (webkit prefix) | | Firefox | ❌ Not supported |

Note: The Web Speech API requires HTTPS in production (except localhost).

SSR / Next.js

This package is SSR-safe. The Web Speech API is only accessed on the client.

Next.js App Router

'use client'

import { useSpeechInput } from '@syntropy-labs/react-web-speech'

export function VoiceButton() {
  const { isListening, toggle, isSupported } = useSpeechInput()
  
  if (!isSupported) return null
  
  return (
    <button onClick={toggle}>
      {isListening ? 'Stop' : 'Speak'}
    </button>
  )
}

Next.js Pages Router

import dynamic from 'next/dynamic'

const VoiceInput = dynamic(
  () => import('../components/VoiceInput'),
  { ssr: false }
)

TypeScript

All types are exported:

import type {
  UseSpeechInputOptions,
  UseSpeechInputReturn,
  UseSpeechInputWithCursorOptions,
  UseSpeechInputWithCursorReturn,
  SpeechError,
  SpeechErrorType,
  MicPermissionState,
  CursorPosition,
  BrowserCapabilities,
} from '@syntropy-labs/react-web-speech'

Advanced Examples

Voice-controlled Form

import { useState, useRef } from 'react'
import { useSpeechInputWithCursor } from '@syntropy-labs/react-web-speech'

function VoiceForm() {
  const [formData, setFormData] = useState({ name: '', email: '' })
  const [activeField, setActiveField] = useState<'name' | 'email'>('name')
  const inputRefs = {
    name: useRef<HTMLInputElement>(null),
    email: useRef<HTMLInputElement>(null),
  }

  const { toggle, isListening } = useSpeechInputWithCursor({
    inputRef: inputRefs[activeField],
    value: formData[activeField],
    onChange: (value) => setFormData({ ...formData, [activeField]: value }),
  })

  return (
    <form>
      <input
        ref={inputRefs.name}
        value={formData.name}
        onFocus={() => setActiveField('name')}
        onChange={(e) => setFormData({ ...formData, name: e.target.value })}
        placeholder="Name"
      />
      <input
        ref={inputRefs.email}
        value={formData.email}
        onFocus={() => setActiveField('email')}
        onChange={(e) => setFormData({ ...formData, email: e.target.value })}
        placeholder="Email"
      />
      <button type="button" onClick={toggle}>
        {isListening ? '🔴 Stop' : '🎙️ Speak'}
      </button>
    </form>
  )
}

Real-time Transcript Display

import { useSpeechInput } from '@syntropy-labs/react-web-speech'

function LiveTranscript() {
  const { transcript, interimTranscript, isListening, toggle } = useSpeechInput({
    interimResults: true,
    continuous: true,
  })

  return (
    <div>
      <button onClick={toggle}>{isListening ? 'Stop' : 'Start'}</button>
      <p>
        {transcript}
        <span style={{ opacity: 0.5 }}>{interimTranscript}</span>
      </p>
    </div>
  )
}

Troubleshooting

"Permission denied" error

The user has denied microphone access. They need to:

1. Click the 🔒 icon in the browser address bar
2. Reset microphone permissions
3. Refresh the page

"Network error"

The Web Speech API requires an internet connection. Chrome sends audio to Google's servers for processing.

Recognition stops immediately

Some browsers stop recognition after detecting silence. Solutions:

• Use continuous: true for longer sessions
• Increase silenceTimeout (or set to 0 to disable)

Works in development but not production

The Web Speech API requires HTTPS. Make sure your production site uses SSL.

Duplicate React error with yarn link

When testing locally with yarn link, add React aliases to your Vite config:

// vite.config.ts
import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      react: path.resolve('./node_modules/react'),
      'react-dom': path.resolve('./node_modules/react-dom'),
    },
  },
})

Why This Package?

Existing React speech-to-text packages lack critical production-ready features:

| Feature | Other Packages | This Package | |---------|---------------|--------------| | Mic permission state | ❌ | ✅ | | Insert text at cursor | ❌ | ✅ | | Auto-silence detection | ❌ | ✅ | | Auto-restart on errors | ❌ | ✅ | | TypeScript-first | Varies | ✅ | | React 18 Strict Mode | ❌ | ✅ |

Contributing

Contributions are welcome! Please read our Contributing Guide first.

# Clone the repo
git clone https://github.com/SyntropyLabs/react-web-speech.git
cd react-web-speech

# Install dependencies
yarn install

# Run tests
yarn test

# Type check
yarn typecheck

# Build
yarn build

License

MIT © SyntropyLabs