Quickstart

This guide gets SpeechUI running in your app. We'll install the kit for your framework, wrap your app in ListensProvider with your license key, add a listening bar or popup, drop in your first speech-aware control, and set light or dark mode.

Choose your framework

There are three SDKs available today: React and Angular for the browser, and React Native for iOS and Android apps built with Expo.

# Install the SpeechUI React SDK
npm install @listenssoft/speechui-react

Add ListensProvider

ListensProvider runs speech recognition and the press-and-hold-to-talk gesture, and every control inside it picks up the transcript automatically. Add it once, at the root of your app:

• React: wrap your app in ListensProvider, usually in App.tsx.
• React Native: wrap your root component in ListensProvider. That's App.tsx, or app/_layout.tsx with Expo Router. Add the expo-speech-recognition config plugin to app.json too, so the app asks for microphone and speech permissions. See the React Native setup.
• Angular: there's no provider component. Register the kit with provideListens in app.config.ts, then put the listensRoot directive on your root component's outer element (app.ts, or app.component.ts in projects created before Angular 20). That element is the press-and-hold surface.

Replace YOUR_LICENSE_KEY with your own key. Get your license key.

import { ListensProvider } from '@listenssoft/speechui-react';
// Optional default styles for the controls.
import '@listenssoft/speechui-react/dist/listens-default.css';

export function App() {
  return (
    <ListensProvider licenseKey="YOUR_LICENSE_KEY">
      {/* …the rest of your app */}
    </ListensProvider>
  );
}

Add a ListeningBar or ListeningPopup

The provider never renders a listening surface, so people can't see that they're being heard until you add one. Most apps want one, placed first inside the provider (in Angular, first inside the listensRoot element). Pick one of the two:

• ListeningBar: a full-width strip pinned to the top of the page, with the wave and the live transcript.
• ListeningPopup: a compact capsule that floats over the page and widens to fit the transcript.

import { ListensProvider, ListeningBar } from '@listenssoft/speechui-react';
// Optional default styles for the controls.
import '@listenssoft/speechui-react/dist/listens-default.css';

export function App() {
  return (
    <ListensProvider licenseKey="YOUR_LICENSE_KEY">
      <ListeningBar />
      {/* …the rest of your app */}
    </ListensProvider>
  );
}

To use the popup instead, import ListeningPopup and render it in the same place. In Angular, that's ListensListeningPopupComponent and <listens-listening-popup />. Only the most recently mounted bar or popup shows. In React Native the popup is absolutely positioned and anchors to its parent, so keep it at the root.

See every option on the listening bar & popup page for React, Angular, or React Native.

Add your first Listens-capable component

Each SpeechUI control takes a command: the word people say to target it. Here's a text field with the command name. Render it anywhere inside the provider, then hold anywhere on the page and say "name Jane Doe". The field claims the phrase and fills in "Jane Doe" as you speak, and onMatch fires once with the final value when listening stops.

import { ListensTextField } from '@listenssoft/speechui-react';
import { useState } from 'react';

export function NameField() {
  const [name, setName] = useState('');
  return (
    <ListensTextField
      label="Name"
      command="name"
      value={name}
      onChange={(e) => setName(e.target.value)}
      onMatch={setName}
    />
  );
}

Browse every control, with live demos, for React, Angular, or React Native.

Light and dark mode

Every SpeechUI component, including the listening bar and popup, comes in a light and a dark theme. Out of the box they follow the device: light when it's set to light mode, dark when it's set to dark mode. There's nothing to set up for that.

If your app has its own theme switch, set the theme yourself and every component follows it:

• React and Angular: set data-listens-theme="dark" or "light" on the <html> element. Remove the attribute to follow the device again. It has to be on <html>; a wrapper element won't work.
• React Native: pass LISTENS_DARK_THEME or LISTENS_LIGHT_THEME to the theme prop of ListensProvider. Leave theme out to follow the device again.

Here's a dark mode switch for each framework. It's a ListensToggle, so people can tap it or just say "dark mode". In React, render it anywhere inside the provider. In Angular, render it anywhere inside the listensRoot element.

import { ListensToggle } from '@listenssoft/speechui-react';
import { useState } from 'react';

export function DarkModeToggle() {
  // Start from the device setting, so the switch matches what's on screen.
  const [dark, setDark] = useState(
    () => window.matchMedia('(prefers-color-scheme: dark)').matches,
  );

  function changeTheme(next: boolean) {
    setDark(next);
    // Every SpeechUI component switches to this theme.
    document.documentElement.setAttribute(
      'data-listens-theme',
      next ? 'dark' : 'light',
    );
  }

  return (
    <ListensToggle
      label="Dark mode"
      command="dark mode"
      checked={dark}
      onChange={changeTheme}
    />
  );
}

The theme only covers SpeechUI's own components. Switch the rest of your app's colors from the same place, the way you do today.

What's next?

You're now set up with SpeechUI and have a working speech-aware control. Here are a few links that might be handy next:

• Get your license key
• Browse the components for React, Angular, or React Native
• Try every control in the Control Gallery