Avatar Component

The <Avatar /> component renders a 3D talking avatar with AI-powered conversation capabilities.

Import

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

Basic Usage

<Avatar
  apiKey="av_live_xxxxx"
  avatarId="aria-001"
/>

Props

Required Props

Prop	Type	Description
`apiKey`	`string`	Your Avatarium API key
`avatarId`	`string`	ID of the avatar to render

Optional Props

Prop	Type	Default	Description
`className`	`string`	`""`	CSS class for the container
`style`	`CSSProperties`	`{}`	Inline styles for container
`aiProvider`	`"groq" \| "openai" \| "anthropic" \| "gemini"`	`"groq"`	AI model provider
`ttsProvider`	`"google" \| "elevenlabs" \| "browser"`	`"google"`	Text-to-speech provider
`voiceId`	`string`	Avatar default	Voice ID for TTS
`systemPrompt`	`string`	Avatar default	System prompt for AI
`autoConnect`	`boolean`	`true`	Auto-connect on mount

Event Props

Prop	Type	Description
`onConnected`	`() => void`	Called when connection established
`onDisconnected`	`() => void`	Called when connection closed
`onMessage`	`(msg: Message) => void`	Called when message received
`onError`	`(err: Error) => void`	Called on error
`onSpeakStart`	`() => void`	Called when avatar starts speaking
`onSpeakEnd`	`() => void`	Called when avatar stops speaking

Examples

With Custom AI Provider

<Avatar
  apiKey={process.env.NEXT_PUBLIC_AVATARIUM_KEY}
  avatarId="aria-001"
  aiProvider="anthropic"
  systemPrompt="You are a helpful customer support agent."
/>

With Event Handlers

<Avatar
  apiKey={process.env.NEXT_PUBLIC_AVATARIUM_KEY}
  avatarId="aria-001"
  onConnected={() => console.log('Connected!')}
  onMessage={(msg) => {
    if (msg.role === 'assistant') {
      console.log('Avatar said:', msg.content);
    }
  }}
  onError={(err) => {
    console.error('Avatar error:', err);
  }}
/>

With Custom Styling

<Avatar
  apiKey={process.env.NEXT_PUBLIC_AVATARIUM_KEY}
  avatarId="aria-001"
  className="rounded-2xl shadow-xl"
  style={{ width: '400px', height: '400px' }}
/>

Ref API

You can access the avatar instance via ref:

import { useRef } from 'react';
import { Avatar, AvatarRef } from '@avatarium/react';
 
function App() {
  const avatarRef = useRef<AvatarRef>(null);
 
  const handleSend = () => {
    avatarRef.current?.sendMessage('Hello!');
  };
 
  return (
    <>
      <Avatar ref={avatarRef} apiKey="..." avatarId="aria-001" />
      <button onClick={handleSend}>Send Message</button>
    </>
  );
}

Ref Methods

Method	Type	Description
`sendMessage`	`(text: string) => Promise<void>`	Send a message
`speak`	`(text: string) => Promise<void>`	Make avatar speak text
`stop`	`() => void`	Stop current speech
`disconnect`	`() => void`	Close connection
`connect`	`() => Promise<void>`	Reconnect

Overview Hooks