Orb

npx shadcn@latest add "@assistant-ui/voice"

npx assistant-ui@latest init

import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/ai-sdk";

export default function App() {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({ api: "/api/chat" }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {/* your components */}
    </AssistantRuntimeProvider>
  );
}

npx shadcn@latest add "@assistant-ui/elements-voice"

Orb is the realtime voice surface: an animated indicator plus connect, mute, and disconnect actions. With a runtime it reads a live RealtimeVoiceAdapter session directly; standalone you drive the same orb and buttons from state and callbacks you own.

Getting started

import { useChatRuntime } from "@assistant-ui/ai-sdk";

const runtime = useChatRuntime({
  adapters: {
    voice: myVoiceAdapter,
  },
});

import { Thread } from "@/components/assistant-ui/elements/thread.aui";
import {
  VoiceControl,
  VoiceOrb,
} from "@/components/assistant-ui/elements/voice.aui";
import { AuiIf } from "@assistant-ui/react";

export default function Chat() {
  return (
    <div className="flex h-full flex-col">
      <AuiIf condition={(s) => s.thread.capabilities.voice}>
        <div className="flex items-center justify-center py-6">
          <VoiceOrb />
        </div>
        <VoiceControl />
      </AuiIf>
      <div className="min-h-0 flex-1">
        <Thread />
      </div>
    </div>
  );
}

"use client";

import { useState } from "react";
import {
  VoiceOrb,
  type VoiceOrbState,
} from "@/components/assistant-ui/elements/voice";

export function Call() {
  const [state, setState] = useState<VoiceOrbState>("idle");
  return <VoiceOrb state={state} volume={0} />;
}

<VoiceOrb state={state} volume={micLevel} />

Anatomy

<canvas className="aui-voice-orb" data-state={/* idle | connecting | listening | speaking | muted */} />

<div className="aui-voice-control">
  <span /> {/* status dot, colored by state */}
  {/* no session, or an ended one: */}
  <button>Connect</button>
  {/* starting: */}
  <span>Connecting...</span>
  {/* running: */}
  <button aria-label="Mute or Unmute" />
  <button aria-label="Disconnect" />
</div>

The orb's five states resolve in a fixed order: no session at all, or a session whose status is "ended", is idle; a session whose status is "starting" is connecting, regardless of mute; otherwise a muted session is muted, even while the model is talking; otherwise the session's mode decides speaking or listening. VoiceControl follows a simpler split: no session or an ended one shows the connect button, a starting session shows only the "Connecting..." text, and a running session shows mute and disconnect. The status dot is grey while idle, a pulsing amber while connecting, green while listening or speaking, and red while muted.

Examples

States

{(["idle", "connecting", "listening", "speaking", "muted"] as const).map(
  (state) => (
    <VoiceOrb key={state} state={state} />
  ),
)}

import { VoiceOrb } from "@/components/assistant-ui/elements/voice";

{(["idle", "connecting", "listening", "speaking", "muted"] as const).map(
  (state) => (
    <VoiceOrb key={state} state={state} />
  ),
)}

Palettes

Both lanes take a variant, a color axis independent of state: default (grey), blue, violet, or emerald.

<VoiceOrb variant="violet" />

Where sessions come from

function ComposerVoiceToggle() {
  const voiceState = useVoiceState();
  const { connect, disconnect } = useVoiceControls();
  const isActive =
    voiceState?.status.type === "running" ||
    voiceState?.status.type === "starting";

  return (
    <AuiIf condition={(s) => s.thread.capabilities.voice}>
      <button
        type="button"
        onClick={() => (isActive ? disconnect() : connect())}
        aria-label={isActive ? "End voice" : "Start voice"}
      >
        {isActive ? <PhoneOffIcon /> : <PhoneIcon />}
      </button>
    </AuiIf>
  );
}

<VoiceOrb
  state={isMuted ? "muted" : isSpeaking ? "speaking" : "listening"}
  volume={micLevel}
/>

API reference