@avatarium/react

React SDK for Avatarium — embed AI avatars in your web app.

Installation

npm install @avatarium/react

Quick Start (Recommended)

The simplest way to embed an avatar — just drop in AvatariumEmbed:

import { AvatariumEmbed } from '@avatarium/react';

function App() {
  return (
    <AvatariumEmbed
      shortId="YOUR_AVATAR_ID"
      onReady={(data) => console.log('Ready:', data.avatar)}
      onTranscript={(text) => console.log('User said:', text)}
      style={{ width: '100%', height: '600px' }}
    />
  );
}

With Controls

Use useAvatariumEmbed for programmatic control:

import { AvatariumEmbed, useAvatariumEmbed } from '@avatarium/react';

function App() {
  const { ref, speak, startVoice, stopVoice } = useAvatariumEmbed();

  return (
    <div>
      <AvatariumEmbed
        ref={ref}
        shortId="YOUR_AVATAR_ID"
        mode="voice"
        style={{ width: '100%', height: '600px' }}
      />
      <div style={{ display: 'flex', gap: 8, padding: 16 }}>
        <button onClick={() => speak('Hello!')}>Say Hello</button>
        <button onClick={startVoice}>🎙️ Start Voice</button>
        <button onClick={stopVoice}>⏹️ Stop</button>
      </div>
    </div>
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | shortId | string | required | Avatar ID from your dashboard | | host | string | 'https://avatarium.ai' | API host | | mode | 'voice' \| 'chat' | 'chat' | Widget mode | | style | CSSProperties | — | Container style | | className | string | — | CSS class | | onReady | (data) => void | — | Avatar loaded | | onStateChange | (state) => void | — | Voice state changed | | onSpeakStart | () => void | — | Avatar started speaking | | onSpeakEnd | () => void | — | Avatar stopped speaking | | onTranscript | (text) => void | — | User speech transcribed | | onError | (error) => void | — | Error occurred |

Ref Methods

• speak(text, { mood?, speed? }) — Make the avatar speak
• stopSpeaking() — Interrupt speech
• startVoice() — Start voice mode (microphone)
• stopVoice() — Stop voice mode
• setMood(mood) — Set avatar mood
• setVolume(volume) — Set volume (0-1)
• resumeAudio() — Unlock audio context

How It Works

AvatariumEmbed loads the Avatarium widget in an iframe and communicates via postMessage. This means:

• Zero 3D setup — all rendering handled by the widget
• Automatic updates — improvements apply instantly
• Tiny bundle — no Three.js in your app
• Full features — voice chat, text chat, TTS, STT, lip-sync