Skip to main content

Speech Component

API Reference

Here is the full API for the <Speech> component, these properties can be set on an instance of <Speech>:

ParameterTypeRequiredDefaultDescription
textReact.ReactNodeYes-It contains the text to be spoken by Web Speech API.
idstringNoautoA unique identifier for the <Speech> instance. Must match the id of the corresponding <HighlightedText> component to link them together.
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.
startBtnButtonNo<HiVolumeUp />Button to start the speech instance.
pauseBtnButtonNo<HiVolumeOff />Button to pause the speech instance.
stopBtnButtonNo<HiMiniStop />Button to stop the speech instance.
useStopOverPausebooleanNofalseWhether the controls should display stopBtn instead of pauseBtn. In Android devices, SpeechSynthesis.pause() behaves like SpeechSynthesis.cancel(). See details
enableConditionalHighlightbooleanNofalseIf true, allows <Speech> to correctly render speech markup even when the corresponding <HighlightedText> is conditionally mounted or unmounted. May impact performance in large applications.
propsDivPropsNo-Props passed directly to the wrapper <div> rendered by <Speech>.
childrenChildrenNo-See usage with FaC
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

Button

import { JSX } from "react";

type Button = JSX.Element | string | null;

Children

import { ReactNode } from "react";

type SpeechStatus = "started" | "paused" | "stopped" | "queued";
type VoidFunction = () => void;
type ChildrenOptions = {
speechStatus?: SpeechStatus;
isInQueue?: boolean;
start?: VoidFunction;
pause?: VoidFunction;
stop?: VoidFunction;
};
type Children = (childrenOptions: ChildrenOptions) => ReactNode;

DivProps

import { DetailedHTMLProps, HTMLAttributes } from "react";

type DivProps = DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>;

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";