Voice selector

Searches application-supplied voice names and metadata, with controlled selection and optional audio preview playback.

Preview

Voice

Mina

A supplied catalog entry for a calm reading voice.

Example provider · English · Warm · Measured

In action

Choose from a supplied voice catalog

Voice

Mina

A supplied catalog entry for a calm reading voice.

Example provider · English · Warm · Measured

Search names, languages, and metadata in this example catalog. The application supplies its provider’s voices. A previewSrc and previewText enable a real sample with a readable text alternative; selection alone does not generate speech.

When to use

Use it for

Supply provider voice records; name, provider, language, description and attributes all participate in search.
Use value/onValueChange or defaultValue for voice selection.
Supply previewSrc for a real audio sample and previewText for speech's text alternative.
Sample playback begins only after Preview voice. Selection changes or unmount stop this selector's previous sample.
CSS-only markup provides selection paint; search and sample playback need application code.

Avoid

Assuming this picker fetches a provider catalog or changes a speech engine by itself.
Inferring voice metadata instead of using the provider's supplied descriptions.

Install

React package

npm install @noorddev/vlak-react

Load the stylesheet once at your app root, then import the components you use.

import "@noorddev/vlak-react/css";
import { VoiceSelector } from "@noorddev/vlak-react";

Per-component imports are available at @noorddev/vlak-react/components/voice-selector.

Copy the source

npx @noorddev/vlak-cli add voice-selector

Adds the component and its dependencies to components/vlak/. Follow the StyleX setup to compile the source in your application.

shadcn registry

npx shadcn add https://vlak.dev/r/voice-selector.json

Installs the same source through the shadcn CLI.

React

"use client";
import { useState } from "react";
import { VoiceSelector } from "@noorddev/vlak-react";

export function VoicePicker({ sampleUrl }: { sampleUrl?: string }) {
  const [voiceId, setVoiceId] = useState("mina");
  return <VoiceSelector value={voiceId} onValueChange={setVoiceId} voices={[
    { id: "mina", name: "Mina", provider: "Your provider", language: "English", attributes: ["Warm"], previewSrc: sampleUrl, previewText: "A short sample of this voice." },
    { id: "noor", name: "Noor", provider: "Your provider", language: "Dutch" },
  ]} />;
}

See the integration example to compose these components with your application's model and data.

Props

VoiceSelector

Supplied voice metadata and optional real audio samples; provider catalogs remain application-owned.

Prop	Type	Default
`voices`required	`readonly VoiceOption[]`
`value`	`string`
`defaultValue`	`string`	`""`
`onValueChange`	`(voiceId: string) => void`
`label`	`string`	`"Voice"`
`disabled`	`boolean`	`false`

Also accepts Omit<HTMLAttributes<HTMLDivElement>, "defaultValue">.

The ref reaches HTMLDivElement.

Keyboard

Keys	Does
`Type`	Filters voice names and supplied metadata
`Arrow Down, Arrow Up, Enter`	Navigates and selects a voice
`Escape`	Closes the voice list
`Enter, Space`	Starts or stops the selected voice sample

Accessibility

The visible label names the shared Combobox; disabled voices are skipped by keyboard navigation.
Preview errors use a status region and permit retry. Samples never autoplay.
The selected voice's metadata uses a subtle 1px frame with 4px corners. Native div attributes and ref are forwarded.

Markup

The same styles are available as CSS. Native HTML provides the static presentation; React or application code supplies state updates and actions.

npm install @noorddev/vlak

import "@noorddev/vlak/css";

<div class="rs-voice-selector"><label class="rs-voice-selector-label" for="voice">Voice</label><select class="rs-input" id="voice"><option>Mina · English</option><option>Noor · Dutch</option></select></div>

Classes

.rs-voice-selector.rs-voice-selector-label.rs-voice-selector-option.rs-voice-selector-metadata.rs-voice-selector-detail.rs-voice-selector-message

Depends on

Button Combobox Input

Use elsewhere

Markdown reference Registry JSON Source AI integration guide