Wraps the browser's SpeechSynthesis API in a single button. Click to speak; click again while speaking to stop. Works in all modern browsers (Chromium, Firefox, Safari).

Basic Usage

The text attribute holds the phrase to read aloud.

<k-text-to-speech text="Hello, world!"></k-text-to-speech>

Slotted Text

If text is not set, the element's text content is spoken. Useful when the text is longer or already lives in the DOM.

<k-text-to-speech>The quick brown fox jumps over the lazy dog.</k-text-to-speech>

Rate & Pitch

Tune playback with the rate (0.1–10, default 1) and pitch (0–2, default 1) attributes. volume (0–1, default 1) is also available.

<k-text-to-speech text="Wow that is fast" rate="2"></k-text-to-speech>
<k-text-to-speech text="A bit higher pitch" pitch="1.6"></k-text-to-speech>

Language

Set language to a BCP‑47 tag to pick a localized voice (browser-dependent — the OS-installed voices determine availability).

<k-text-to-speech text="Bonjour le monde" language="fr-FR"></k-text-to-speech>

Voice Selection

Set voice to a specific voice name. The component looks it up in speechSynthesis.getVoices(); if the name isn't installed on the user's device the component silently falls back to the language default. Voice availability varies by browser and OS — here's a quick reference:

There is no voice name that is identical across every platform. For portable code, prefer language over voice — the browser will pick the best installed voice for that language tag. Only set voice when you specifically want one and accept the device-dependent fallback.

<k-text-to-speech text="Hello, this is Google US English" voice="Google US English"></k-text-to-speech>
<k-text-to-speech text="Hello in French (browser picks a voice)" language="fr-FR"></k-text-to-speech>

Voice Fallback Chain

The voice attribute accepts a comma-separated list (like CSS font-family). The component tries each name in order and uses the first one installed; if none match it falls back to the language default.

<k-text-to-speech text="Trying Samantha first, then a Google fallback" voice="Samantha, Google US English, Microsoft Zira"></k-text-to-speech>

Dynamic Text

Set the text property at runtime to read whatever is in an input or other DOM source.

<k-text-to-speech id="ttsExample"></k-text-to-speech>
<input id="ttsInput" type="text" value="Type something then click the button" />
<script>
  const $tts = document.getElementById('ttsExample');
  const $input = document.getElementById('ttsInput');
  $input.addEventListener('input', () => {
    $tts.text = $input.value;
  });
  $tts.text = $input.value;
</script>

Disabled

The disabled attribute prevents user interaction. The button also auto-disables when the browser doesn't support the SpeechSynthesis API.

<k-text-to-speech disabled text="You can't hear this"></k-text-to-speech>

JavaScript Reference

Constructor

Extends ShadowComponent

new TextToSpeech()

Requirements

• ShadowComponent
• A browser with window.speechSynthesis (all major modern browsers)

Properties

text: String

The text to speak. When empty, the element's slotted text content is used. Syncs to text attribute.

voice: String

Optional voice name, or a comma-separated fallback chain (e.g. "Samantha, Google US English, Microsoft Zira"). Each name is matched against speechSynthesis.getVoices() in order; the first installed match wins. If none match, the component falls back to the default voice for the configured language. Syncs to voice attribute.

language: String

BCP‑47 language tag (e.g. "en-US", "fr-FR"). Default is empty (browser default). Syncs to language attribute.

rate: Number

Speech rate from 0.1 (slow) to 10 (fast). Default is 1. Syncs to rate attribute.

pitch: Number

Pitch from 0 to 2. Default is 1. Syncs to pitch attribute.

volume: Number

Volume from 0 (silent) to 1 (loud). Default is 1. Syncs to volume attribute.

disabled: Boolean

When true, the button cannot be clicked. Syncs to disabled attribute.

speaking: Boolean

Reflects whether the component is currently speaking. The button shows the stop icon and switches to the active color while true. Syncs to speaking attribute.

Methods

speak(textOverride?): void

Begin speaking. If textOverride is supplied, it is spoken instead of text/slot content. Cancels any in-flight utterance first.

stop(): void

Cancel any speech in progress.

toggle(): void

Calls stop() if currently speaking, otherwise speak() — the same behavior as clicking the button.

CSS Variables

Events

start

Fires when speech begins.

end

Fires when speech finishes (naturally or via stop()).

error

Fires if the underlying SpeechSynthesisUtterance reports an error. detail contains { error: String }.