How to Add a Talking AI Avatar to Your React App in 5 Minutes

You want a 3D avatar in your React app that can actually talk to users. Not a static image. Not a chatbot widget. A real-time, animated character that listens, thinks, and responds with lip-synced speech.

This tutorial gets you there in under 5 minutes using Avatarium's React SDK. Everything runs in an iframe, so there is no WebGL setup, no Three.js boilerplate, and no audio pipeline to configure. You get a component, drop it in, and it works.

What You Will Build

By the end of this tutorial, your React app will have:

A 3D AI avatar rendered in your page
Voice chat (push-to-talk or hands-free)
Text chat as a fallback
Real-time lip sync and animations
Event hooks for state changes

Total code: about 15 lines.

Prerequisites

A React project (Next.js, Vite, Create React App all work)
An Avatarium account (free signup)
An avatar created in the dashboard (takes 30 seconds)

Step 1: Install the SDK

npm install @avatarium/react

That is it. No peer dependencies beyond React 18+.

Step 2: Get Your Avatar's Short ID

Log into the Avatarium dashboard, go to your avatar's settings page, and copy the Short ID. It looks something like abc1def2ghi.

This ID is public and safe to embed in client-side code. It identifies which avatar to load but does not grant any write access to your account.

Step 3: Drop In the Component

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

export default function ChatPage() {
  return (
    <div style={{ width: 400, height: 600 }}>
      <AvatariumEmbed
        shortId="your-avatar-short-id"
        mode="voice"
        onReady={({ avatar }) => console.log('Avatar loaded:', avatar.name)}
      />
    </div>
  );
}

That is the minimum viable integration. The avatar loads, renders in 3D, and is ready for conversation. Users can speak to it or type messages.

Step 4: Switch Between Voice and Chat Modes

The mode prop controls the default interaction style:

"voice" starts in voice chat mode (microphone active)
"chat" starts with a text input field

Users can switch between modes inside the widget. The prop just sets the default.

<AvatariumEmbed
  shortId="abc1def2ghi"
  mode="chat"
  style={{ width: '100%', height: '100vh' }}
/>

Step 5: Listen to Events

The component exposes several event callbacks:

import { useRef } from 'react';
import { AvatariumEmbed, type AvatariumEmbedHandle } from '@avatarium/react';

export default function AvatarPage() {
  const ref = useRef<AvatariumEmbedHandle>(null);

  return (
    <AvatariumEmbed
      ref={ref}
      shortId="abc1def2ghi"
      onReady={({ avatar, thumbnail }) => {
        console.log('Loaded:', avatar.name);
        console.log('Thumbnail:', thumbnail);
      }}
      onStateChange={({ state }) => {
        // 'idle' | 'listening' | 'thinking' | 'speaking'
        console.log('Avatar state:', state);
      }}
    />
  );
}

The ref gives you imperative control. You can programmatically send messages, toggle voice mode, or reset the conversation.

Controlling the Avatar Programmatically

Through the ref, you can call methods like:

// Send a text message as if the user typed it
ref.current?.sendMessage('Tell me about yourself');

// Programmatically end the current session
ref.current?.resetConversation();

This is useful for guided experiences where you want to trigger specific avatar responses based on user actions in your app, not just typed or spoken input.

Styling and Layout

The component fills its container. Set width and height on the parent element:

// Full-page avatar
<div style={{ width: '100vw', height: '100vh' }}>
  <AvatariumEmbed shortId="abc1def2ghi" />
</div>

// Sidebar widget
<div style={{ width: 360, height: 640, position: 'fixed', right: 16, bottom: 16 }}>
  <AvatariumEmbed shortId="abc1def2ghi" mode="chat" />
</div>

// With Tailwind CSS
<div className="w-[400px] h-[600px] rounded-2xl overflow-hidden shadow-xl">
  <AvatariumEmbed shortId="abc1def2ghi" />
</div>

The iframe has no visible border by default. Add border-radius and overflow: hidden on the container for rounded corners.

Next.js Specific Notes

The SDK is marked 'use client' internally, so it works in Next.js App Router without any extra configuration. Just import and use it in a client component:

'use client';

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

export default function AvatarSection() {
  return (
    <section className="flex justify-center py-12">
      <div className="w-[400px] h-[600px]">
        <AvatariumEmbed shortId="abc1def2ghi" mode="voice" />
      </div>
    </section>
  );
}

For Pages Router, it works the same way since all components are client-rendered by default.

What Happens Behind the Scenes

When the component mounts, it creates an iframe pointing to Avatarium's hosted widget. The widget handles:

3D rendering via Three.js and Ready Player Me avatars
Speech-to-text via Groq Whisper (55+ languages)
AI responses from the avatar's configured personality
Text-to-speech via Groq, Deepgram, or ElevenLabs (depending on plan)
Lip sync via phoneme-based viseme mapping in real-time

Your app never touches audio buffers, WebGL contexts, or LLM APIs directly. The iframe is sandboxed and communicates with your app through postMessage events, which the SDK wraps in typed callbacks.

Free Tier Limits

The free plan includes 30 voice minutes per month and one avatar. That is enough to build, test, and demo your integration. When you are ready for production, the Starter plan ($30/month) gives you 500 minutes and 3 avatars.

View all plans

Going Further

Once the basic embed is working, you might want to:

Customize the avatar's personality in the dashboard (system prompt, greeting, voice)
Add knowledge by uploading documents the avatar can reference
Use the chatbot widget for a floating chat bubble instead of an embedded panel
Track usage via the dashboard analytics

The full SDK documentation covers all props, methods, and event types.

Get Started

Create a free account, build your avatar, and paste the component into your React app. First conversation in under 5 minutes.