@polytts/react

React bindings for polytts runtimes.

Use this package when you already have a runtime and want React hooks and provider state around it.

@polytts/react intentionally wraps a low-level TTSRuntime, not the higher-level BrowserTTS controller. In browser apps, you can use either:

• createBrowserTTSRuntime() directly
• createBrowserTTS(...).runtime if you want the simple browser controller elsewhere in your app

If you want the higher-level browser controller state in React, use BrowserTTSProvider and useBrowserTTS().

Install

npm install @polytts/react react

Usage

import { createBrowserTTSRuntime } from "polytts";
import { TTSProvider, useTTS } from "@polytts/react";

const runtime = createBrowserTTSRuntime({
  initialModelId: "browser-speech",
});

function SpeakButton() {
  const { speak, isPreparing, isSpeaking } = useTTS();

  return (
    <button disabled={isPreparing || isSpeaking} onClick={() => void speak("Hello from React.")}>
      Speak
    </button>
  );
}

export function App() {
  return (
    <TTSProvider runtime={runtime}>
      <SpeakButton />
    </TTSProvider>
  );
}

You can also pair it with the simple browser controller:

import { createBrowserTTS } from "polytts";
import { BrowserTTSProvider, useBrowserTTS } from "@polytts/react";

const tts = createBrowserTTS({
  initialModelId: "browser-speech",
});

function FamilyName() {
  const family = useBrowserTTS((value) => value.getSelectedFamily()?.name ?? "none");
  return <span>{family}</span>;
}

export function App() {
  return (
    <BrowserTTSProvider tts={tts}>
      <FamilyName />
    </BrowserTTSProvider>
  );
}

Which provider to use

Use TTSProvider when:

• you already work with a TTSRuntime
• you want lower-level runtime state such as isPreparing, phase, and raw voice resolution
• your app owns model grouping outside polytts

Use BrowserTTSProvider when:

• you want model families, install state, and the higher-level browser controller API
• your app UI switches between families and models directly
• you want controller helpers such as downloadModel(), selectFamily(), and isInstalled()

Browser controller example

import { createBrowserTTS } from "polytts";
import { BrowserTTSProvider, useBrowserTTS } from "@polytts/react";

const tts = createBrowserTTS({
  initialModelId: "browser-speech",
});

function DownloadState() {
  const selectedModelId = useBrowserTTS((value) => value.selectedModelId);
  const isInstalled = useBrowserTTS((value) =>
    selectedModelId ? value.isInstalled(selectedModelId) : false,
  );

  return <span>{isInstalled ? "downloaded" : "not downloaded"}</span>;
}

export function App() {
  return (
    <BrowserTTSProvider tts={tts}>
      <DownloadState />
    </BrowserTTSProvider>
  );
}

SSR and lifecycle notes

• The React providers support server rendering.
• createBrowserTTS() and createBrowserTTSRuntime() are still browser entrypoints, so create them in browser/client code.
• initialModelId and initialVoiceId set the starting selection, but do not eagerly load the model.
• Some models resolve their final voices only after preparation, so a voice picker may need to wait for ready() or selectModel().
• Preference persistence is app-owned. Store selected model, voice, and speed in your own state if you want them restored across reloads.