Orb

PreviousNext

A 3D animated orb with audio reactivity, custom colors, and agent state visualization built with Three.js.

Installation

pnpm dlx @elevenlabs/agents-cli@latest components add orb

Usage

import { Orb } from "@/components/ui/orb"
<Orb />

Examples

Custom Colors

<Orb colors={["#FF6B6B", "#4ECDC4"]} />

With Audio Reactivity

function AudioReactiveOrb() {
  const getInputVolume = () => {
    // Return normalized volume between 0 and 1
    return 0.5
  }
 
  const getOutputVolume = () => {
    // Return normalized volume between 0 and 1
    return 0.7
  }
 
  return (
    <Orb getInputVolume={getInputVolume} getOutputVolume={getOutputVolume} />
  )
}

With Custom Seed

<Orb seed={12345} />

With Agent State

const [agentState, setAgentState] = useState<"thinking" | "listening" | "talking" | null>(null)
 
<Orb agentState={agentState} />

Manual Volume Control

const [inputVolume, setInputVolume] = useState(0.5)
const [outputVolume, setOutputVolume] = useState(0.7)
 
<Orb
  volumeMode="manual"
  manualInput={inputVolume}
  manualOutput={outputVolume}
/>

API Reference

Orb

A WebGL-based 3D orb component with audio reactivity and customizable appearance.

Props

PropTypeDefaultDescription
colors[string, string]["#CADCFC", "#A0B9D1"]Two color values for the gradient
colorsRefRefObject<[string, string]>-Ref for dynamic color updates
resizeDebouncenumber100Canvas resize debounce in ms
seednumberRandomSeed for consistent animations
agentStateAgentStatenullAgent state: null, "thinking", "listening", "talking"
volumeMode"auto" | "manual""auto"Volume control mode
manualInputnumber-Manual input volume (0-1)
manualOutputnumber-Manual output volume (0-1)
inputVolumeRefRefObject<number>-Ref for input volume
outputVolumeRefRefObject<number>-Ref for output volume
getInputVolume() => number-Function returning input volume (0-1)
getOutputVolume() => number-Function returning output volume (0-1)
classNamestring-Custom CSS class

AgentState Type

type AgentState = null | "thinking" | "listening" | "talking"

Notes

  • Built with Three.js and React Three Fiber for performant 3D rendering
  • Uses WebGL shaders for smooth, fluid animations
  • Audio reactivity can be controlled via functions (getInputVolume, getOutputVolume) or refs
  • Agent state changes affect the orb's visual appearance and animation
  • Seed prop ensures consistent animation patterns across renders
  • Automatically handles canvas resizing with configurable debounce
  • Colors can be updated dynamically via colorsRef for smooth transitions
  • Performance-optimized with proper cleanup and requestAnimationFrame usage