Skip to main content

useSpeech Hook

API Reference

Here is the full API for the useSpeech hook, these options can be passed as parameters to the hook:

ParameterTypeRequiredDefaultDescription
textReact.ReactNodeYes-It contains the text to be spoken by Web Speech API.
pitchnumber (0.1 to 2)No1The pitch at which the utterance will be spoken.
ratenumber (0.1 to 10)No1The speed at which the utterance will be spoken.
volumenumber (0 to 1)No1The volume at which the utterance will be spoken.
langstringNo-The language in which the utterance will be spoken.
voiceURIstring | string[]No-The voice using which the utterance will be spoken. If provided an array, further voices will be used as fallback if initial voices are not found. See possible values here.
autoPlaybooleanNofalseAutomatically starts speech when the component loads or when text changes, if set to true.
preserveUtteranceQueuebooleanNofalseWhether to maintain a queue of speech utterances (true) or clear previous utterances (false).
highlightTextbooleanNofalseWhether the words in the text should be highlighted as they are read or not.
showOnlyHighlightedTextbooleanNofalseIf true, returns only the currently highlighted text.
highlightModeHighlightModeNowordDefines the level of text highlighting: word, sentence (highlights until ., ?, !, or \n), line (splits only at \n), or paragraph.
highlightPropsHighlightPropsNo-Props to customize the highlighted word, typically applied to the <mark> tag.
highlightContainerPropsHighlightPropsNo-Props applied to the container wrapping highlighted words typically applied to the <span> tag.
enableDirectivesbooleanNofalseIf true, enables inline processing controls for dynamically adjusting pitch, rate, volume, and other speech parameters, or inserting pauses directly within your text content. See Directives.
updateModeUpdateModeNoimmediateControls how text changes are processed: immediate (updates instantly), throttle (updates at most every updateDelay ms, ideal for AI streaming), or debounce (waits updateDelay ms after changes stop, ideal for user typing).
updateDelaynumber (ms)No0Delay for updateMode = throttle or debounce. Has no effect when updateMode is immediate.
maxChunkSizenumber (minimum 50)No250Specifies the maximum size of each text chunk when dividing the text. This helps manage the Web Speech API's text limit, avoiding issues related to large text inputs.
onErrorSpeechSynthesisErrorHandlerNoconsole.errorFunction to be executed if browser doesn't support Web Speech API.
onStartSpeechSynthesisEventHandlerNo-Function to be executed when speech utterance is started.
onResumeSpeechSynthesisEventHandlerNo-Function to be executed when speech utterance is resumed.
onPauseSpeechSynthesisEventHandlerNo-Function to be executed when speech utterance is paused.
onStopSpeechSynthesisEventHandlerNo-Function to be executed when speech utterance is stopped.
onBoundarySpeechSynthesisBoundaryEventHandlerNo-Function to be executed during speech synthesis that provides progress updates. Fires at the start (0%), at word/sentence boundaries during speech (1-99%), and at completion (100%).
onQueueChangeQueueChangeEventHandlerNo-Function to be executed whenever queue changes.

Types

HighlightMode

type HighlightMode = "word" | "sentence" | "line" | "paragraph";

HighlightProps

import { CSSProperties } from "react";

type HighlightProps = {
className?: string;
id?: string;
style?: CSSProperties;
title?: string;
};

QueueChangeEventHandler

type SpeechUtterancesQueue = Partial<SpeechSynthesisUtterance>[];
type QueueChangeEventHandler = (queue: SpeechUtterancesQueue) => void;

SpeechSynthesisBoundaryEventHandler

type SpeechSynthesisBoundaryEvent = { progress: number };
type SpeechSynthesisBoundaryEventHandler = (event: SpeechSynthesisBoundaryEvent) => void;

SpeechSynthesisErrorHandler

type SpeechSynthesisErrorHandler = (error: Error) => void;

SpeechSynthesisEventHandler

type SpeechSynthesisEventHandler = () => void;

UpdateMode

type UpdateMode = "immediate" | "throttle" | "debounce";