@avatarium/react-native

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

Installation

npm install @avatarium/react-native react-native-webview
# or
yarn add @avatarium/react-native react-native-webview

For iOS, run cd ios && pod install.

Quick Start

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

export default function App() {
  return (
    <AvatariumEmbed
      shortId="YOUR_AVATAR_ID"
      onReady={(data) => console.log('Avatar ready:', data.avatar)}
      onTranscript={(text) => console.log('User said:', text)}
      style={{ flex: 1 }}
    />
  );
}

With Controls

import { AvatariumEmbed, useAvatariumEmbed } from '@avatarium/react-native';
import { View, Button } from 'react-native';

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

  return (
    <View style={{ flex: 1 }}>
      <AvatariumEmbed
        ref={ref}
        shortId="YOUR_AVATAR_ID"
        mode="voice"
        style={{ flex: 1 }}
      />
      <View style={{ flexDirection: 'row', padding: 16, gap: 8 }}>
        <Button title="Say Hello" onPress={() => speak('Hello!')} />
        <Button title="🎙️ Start" onPress={startVoice} />
        <Button title="⏹️ Stop" onPress={stopVoice} />
      </View>
    </View>
  );
}

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 | ViewStyle | — | Container style | | 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

Use useAvatariumEmbed() or useRef<AvatariumEmbedHandle>():

• 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

Requirements

• React Native ≥ 0.70
• react-native-webview ≥ 13.0
• iOS: microphone permission in Info.plist
• Android: RECORD_AUDIO permission in AndroidManifest.xml

How It Works

The SDK loads the Avatarium voice widget in a WebView and communicates via postMessage. This approach ensures:

• Consistent rendering across iOS and Android
• Automatic updates — widget improvements apply instantly
• Small bundle size — no 3D engine in your app
• Full feature parity with the web widget