Interactive Orb

A beautiful, animated interactive orb component for AI assistants. Powered by procedural particle sphere with real-time state mixing and voice amplitude reactivity.

Features

• ✨ Procedural particle sphere - 720 particles arranged in a golden ratio pattern
• 🎨 Multiple states - idle, connecting, listening, thinking, speaking, error, disabled
• 🎵 Audio reactivity - Responds to voice amplitude for real-time feedback
• 🌈 Customizable colors - Full control over color gradients
• 🎯 State mixing - Smooth transitions between different states
• ♿ Accessibility - Full ARIA support and reduced motion support
• 📱 Responsive - Works on all screen sizes
• ⚡ Performance optimized - Uses requestAnimationFrame and visibility detection

Installation

npm install interactive-orb

Usage

import { InteractiveOrb } from 'interactive-orb';
import { useRef } from 'react';

function App() {
  const audioLevelRef = useRef<number>(0);
  
  return (
    <InteractiveOrb
      state="listening"
      size={400}
      colorFrom="#f0abfc"
      colorTo="#818cf8"
      levelRef={audioLevelRef}
      showAura={true}
    />
  );
}

Props

InteractiveOrb

| Prop | Type | Default | Description | |------|------|---------|-------------| | state | 'idle' \| 'connecting' \| 'listening' \| 'thinking' \| 'speaking' \| 'error' \| 'disabled' | 'idle' | Current state of the orb | | size | number | 460 | Size in pixels | | speed | number | 1 | Animation speed multiplier | | colorFrom | string | '#f0abfc' | Start color for gradient | | colorTo | string | '#818cf8' | End color for gradient | | levelRef | RefObject<number> | undefined | Ref to audio level (0-1) for reactivity | | className | string | undefined | Additional CSS classes | | onDoubleClick | () => void | undefined | Double click handler | | showAura | boolean | true | Show the glowing aura effect |

States

• idle - Default state with gentle breathing animation
• connecting - Orb forms a ring pattern while connecting
• listening - Ripple effect when listening to user input
• thinking - Pulse effect while processing
• speaking - Flow effect when the assistant is speaking
• error - Red color with shake animation
• disabled - Grayed out and reduced opacity

Audio Integration

To make the orb react to audio, provide a level ref:

import { InteractiveOrb } from 'interactive-orb';
import { useRef, useEffect } from 'react';

function App() {
  const audioLevelRef = useRef<number>(0);
  
  // Update audio level from your audio system
  useEffect(() => {
    const updateLevel = (level: number) => {
      audioLevelRef.current = level;
    };
    
    // Connect to your audio analysis system
    // This depends on your audio implementation
  }, []);
  
  return (
    <InteractiveOrb
      state="listening"
      levelRef={audioLevelRef}
    />
  );
}

AI Model Integration

Works with any AI model (OpenAI, Anthropic, Google, etc.):

import { InteractiveOrb } from 'interactive-orb';

function AIAssistant() {
  const [state, setState] = useState('idle');
  const audioLevelRef = useRef<number>(0);
  
  const handleAIPhase = (phase: string) => {
    setState(phase);
  };
  
  return (
    <InteractiveOrb
      state={state}
      levelRef={audioLevelRef}
      size={500}
    />
  );
}

Customization

You can fully customize the appearance:

<InteractiveOrb
  state="speaking"
  size={600}
  speed={1.5}
  colorFrom="#ff6b6b"    // Custom colors
  colorTo="#4ecdc4"
  showAura={false}        // Disable aura
/>

Performance

• Uses requestAnimationFrame for smooth animations
• Automatically pauses when not in viewport
• Respects prefers-reduced-motion preference
• Efficient particle rendering with canvas

Browser Support

• Modern browsers with ES2020 support
• Canvas API support
• Web Audio API (for audio reactivity)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.