Voice Selector

The VoiceSelector component provides a flexible and composable interface for selecting AI voices. Built on shadcn/ui's Dialog and Command components, it features a searchable voice list with support for metadata display (gender, accent, age), grouping, and customizable layouts. The component includes a context provider for accessing voice selection state from any nested component.

Installation

npx ai-elements@latest add voice-selector

Features

• Fully composable architecture with granular control components
• Built on shadcn/ui Dialog and Command components
• React Context API for accessing state in nested components
• Searchable voice list with real-time filtering
• Support for voice metadata with icons and emojis (gender icons, accent flags, age)
• Voice grouping with separators and bullet dividers
• Keyboard navigation support
• Controlled and uncontrolled component patterns
• Full TypeScript support with proper types for all components

Props

<VoiceSelector />

Root Dialog component that provides context for all child components. Manages both voice selection and dialog open states.

<VoiceSelectorTrigger />

Button or element that opens the voice selector dialog.

<VoiceSelectorContent />

Container for the Command component and voice list, rendered inside the dialog.

<VoiceSelectorDialog />

Alternative dialog implementation using CommandDialog for a full-screen command palette style.

<VoiceSelectorInput />

Search input for filtering voices.

<VoiceSelectorList />

Scrollable container for voice items and groups.

<VoiceSelectorEmpty />

Message shown when no voices match the search query.

<VoiceSelectorGroup />

Groups related voices together with an optional heading.

<VoiceSelectorItem />

Selectable item representing a voice.

<VoiceSelectorSeparator />

Visual separator between voice groups.

<VoiceSelectorName />

Displays the voice name with proper styling.

<VoiceSelectorGender />

Displays the voice gender metadata with icons from Lucide. Supports multiple gender identities with corresponding icons.

<VoiceSelectorAccent />

Displays the voice accent metadata with emoji flags representing different countries/regions.

<VoiceSelectorAge />

Displays the voice age metadata with muted styling and tabular numbers for consistent alignment.

<VoiceSelectorDescription />

Displays a description for the voice with muted styling.

<VoiceSelectorAttributes />

Container for grouping voice attributes (gender, accent, age) together. Use with VoiceSelectorBullet for separation.

<VoiceSelectorBullet />

Displays a bullet separator (•) between voice attributes. Hidden from screen readers via aria-hidden.

<VoiceSelectorShortcut />

Displays keyboard shortcuts for voice items.

Hooks

useVoiceSelector()

A custom hook for accessing the voice selector context. This hook allows you to access and control the voice selection state from any component nested within VoiceSelector.

import { useVoiceSelector } from "@repo/elements/voice-selector";

export default function CustomVoiceDisplay() {
  const { value, setValue, open, setOpen } = useVoiceSelector();

  return (
    <div>
      <p>Selected voice: {value ?? "None"}</p>
      <button onClick={() => setOpen(!open)}>
        Toggle Dialog
      </button>
    </div>
  );
}

Return Value