API Reference

Message

Chat message bubble with role-based styling. Uses compound pattern with MessageContent and MessageAvatar.

Conversation

Auto-scrolling container powered by use-stick-to-bottom. Stays pinned to the bottom during streaming.

ChatInput

Multi-modal chat input with auto-resize textarea, keyboard shortcuts (Enter to send), and slots for actions.

Response

Memoized wrapper around Streamdown. Accepts all Streamdown props — renders streaming markdown with syntax highlighting and animations. Only re-renders when children changes.

ThinkingIndicator

Animated loading indicator with three visual variants for AI thinking states.

PromptSuggestions

Grid or list of clickable suggestion cards. Each suggestion has a title, optional description, icon, and value.

Feedback

Thumbs up/down feedback bar with copy and regenerate actions. Designed for AI message responses.

TokenCounter

Token usage display with progress bar, model badge, and optional cost calculation.

AudioPlayer

Compound audio player built on a shared context. Wrap children in AudioPlayerProvider and compose with sub-components.

import {
  AudioPlayerProvider,
  AudioPlayerButton,
  AudioPlayerProgress,
  AudioPlayerTime,
  AudioPlayerDuration,
} from "@/components/ui/audio/audio-player";

const track = { id: "1", src: "/audio/track.mp3", data: { name: "My Track" } };

export function Player() {
  return (
    <AudioPlayerProvider>
      <div className="flex items-center gap-3">
        <AudioPlayerButton item={track} />
        <AudioPlayerProgress />
        <AudioPlayerTime /> / <AudioPlayerDuration />
      </div>
    </AudioPlayerProvider>
  );
}

ScrubBar

Compound timeline scrubber with draggable thumb. Compose ScrubBarContainer > ScrubBarTrack > ScrubBarProgress + ScrubBarThumb.

LiveWaveform

Canvas-based real-time audio waveform from microphone or stream input. Supports scrolling and static rendering modes.

BarVisualizer

Hooks for building real-time frequency bar visualizers. This file exports three hooks — compose them to create custom bar UIs. Uses Web Audio API AnalyserNode under the hood.

Waveform

Waveform family with static, scrolling, scrubber, microphone, live-microphone, and recording variants.

AudioRecorder

Recording component with timer, pause/resume, and audio level meter. Uses MediaRecorder API.

MicSelector

Microphone device picker with permission request handling and mute toggle.

VoiceButton

Multi-state voice interaction button with embedded waveform visualization.

Matrix

SVG dot-matrix display with animation frames and preset patterns. Supports VU meter mode for audio levels.

ShimmeringText

Animated gradient shimmer text effect with viewport-triggered animation using motion/react.

CodeBlock

Syntax-highlighted code block with Shiki, copy button, optional line numbers, and language badge.

SpeechInput

Web Speech API powered speech-to-text input. Supports continuous mode, interim results, and custom rendering via children render prop.

ConversationBar

Text input bar with send button and connection toggle for real-time voice/chat sessions.

TranscriptViewer

Compound transcript display with per-character highlighting, auto-scroll, and synchronized audio playback.

VoicePicker

Selectable voice list with labels, descriptions, and audio preview playback.

Orb

Self-contained canvas orb with organic state motion, glow, pulse rings, and no WebGL or remote texture dependency.

useAudioPlayer

Standalone hook for controlling audio playback with play, pause, seek, volume, and speed. Returns state and actions.

import { useAudioPlayer } from "@/hooks/use-audio-player";

function CustomPlayer() {
  const { isPlaying, currentTime, duration, toggle, seek } = useAudioPlayer({
    src: "/audio/track.mp3",
    onEnded: () => console.log("Track ended"),
  });

  return (
    <div>
      <button onClick={toggle}>{isPlaying ? "Pause" : "Play"}</button>
      <span>{currentTime.toFixed(1)}s / {duration.toFixed(1)}s</span>
    </div>
  );
}

useAudioVolume

Tracks real-time volume/frequency data from a MediaStream using Web Audio API AnalyserNode.

import { useAudioVolume } from "@/hooks/use-audio-volume";

function VolumeMeter({ stream }: { stream: MediaStream | null }) {
  const { data, isActive } = useAudioVolume({ stream, frequencyMode: true });

  // data is a Uint8Array of frequency values (0–255)
  return <div>{isActive ? "Listening..." : "Idle"}</div>;
}

useAudioDevices

Enumerates audio input devices with permission handling, device selection, and stream management.

import { useAudioDevices } from "@/hooks/use-audio-devices";

function DevicePicker() {
  const { devices, hasPermission, requestPermission, selectDevice } =
    useAudioDevices({ kind: "audioinput" });

  if (!hasPermission) {
    return <button onClick={requestPermission}>Allow Microphone</button>;
  }

  return (
    <select onChange={(e) => selectDevice(e.target.value)}>
      {devices.map((d) => (
        <option key={d.deviceId} value={d.deviceId}>{d.label}</option>
      ))}
    </select>
  );
}

useMultibandVolume

Splits raw frequency data into configurable bands for equalizer-style visualization.

useMultibandVolume(data: Uint8Array | null, { bands?: number, minThreshold?: number })

useBarAnimator

Provides smooth bar animation with configurable smoothing/decay. Used internally by BarVisualizer.

useBarAnimator({ targetHeights: number[], smoothing?: number, enabled?: boolean })