useSpeech Hook

API Reference

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

Parameter	Type	Required	Default	Description
text	React.ReactNode	Yes	-	It contains the text to be spoken by Web Speech API.
stableText	boolean	No	false	Skips expensive internal key and chunk calculations and relies on the referential identity of text. Enable this only if the provided text value is stable across renders, for example memoized with useMemo. If the reference changes, the calculations will be recomputed.
pitch	number (0.1 to 2)	No	1	The pitch at which the utterance will be spoken.
rate	number (0.1 to 10)	No	1	The speed at which the utterance will be spoken.
volume	number (0 to 1)	No	1	The volume at which the utterance will be spoken.
lang	string	No	-	The language in which the utterance will be spoken.
voiceURI	string | 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.
autoPlay	boolean	No	false	Automatically starts speech when the component loads or when text changes, if set to true.
preserveUtteranceQueue	boolean	No	false	Whether to maintain a queue of speech utterances (true) or clear previous utterances (false).
highlightText	boolean	No	false	Whether the words in the text should be highlighted as they are read or not.
showOnlyHighlightedText	boolean	No	false	If true, returns only the currently highlighted text.
highlightMode	HighlightMode	No	word	Defines the level of text highlighting: word, sentence (highlights until ., ?, !, or \n), line (splits only at \n), or paragraph.
highlightProps	HighlightProps	No	-	Props to customize the highlighted word, typically applied to the <mark> tag.
highlightContainerProps	HighlightProps	No	-	Props applied to the container wrapping highlighted words typically applied to the <span> tag.
enableDirectives	boolean	No	false	If 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.
updateMode	UpdateMode	No	immediate	Controls 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).
updateDelay	number (ms)	No	0	Delay for updateMode = throttle or debounce. Has no effect when updateMode is immediate.
maxChunkSize	number (minimum 50)	No	250	Specifies 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.
onError	SpeechSynthesisErrorHandler	No	console.error	Function to be executed if browser doesn't support Web Speech API.
onStart	SpeechSynthesisEventHandler	No	-	Function to be executed when speech utterance is started.
onResume	SpeechSynthesisEventHandler	No	-	Function to be executed when speech utterance is resumed.
onPause	SpeechSynthesisEventHandler	No	-	Function to be executed when speech utterance is paused.
onStop	SpeechSynthesisEventHandler	No	-	Function to be executed when speech utterance is stopped.
onBoundary	SpeechSynthesisBoundaryEventHandler	No	-	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%).
onQueueChange	QueueChangeEventHandler	No	-	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";