SDK Reference
React Native

React Native SDK

Use @avatarium/react-native to embed an Avatarium voice avatar inside React Native or Expo apps. The package wraps a hosted Avatarium WebView, so rendering, voice, lip sync, and avatar updates stay on Avatarium infrastructure.

Install

npm install @avatarium/react-native react-native-webview

For Expo projects, install the WebView peer dependency with Expo:

expo install react-native-webview
npm install @avatarium/react-native

Basic embed

import { useRef } from 'react'
import { View } from 'react-native'
import { AvatariumEmbed, type AvatariumEmbedHandle } from '@avatarium/react-native'
 
export default function AvatarScreen() {
  const avatarRef = useRef<AvatariumEmbedHandle>(null)
 
  return (
    <View style={{ flex: 1 }}>
      <AvatariumEmbed
        ref={avatarRef}
        shortId="YOUR_AVATAR_ID"
        mode="voice"
        style={{ flex: 1 }}
        onReady={() => console.log('Avatar ready')}
        onMessage={(message) => console.log('Avatar message:', message)}
      />
    </View>
  )
}

Voice mode requirements

Voice mode uses the hosted Avatarium page inside a WebView. Your app must allow microphone access.

iOS

Add a microphone usage description to Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>This app uses your microphone so you can speak with the avatar.</string>

For Expo, add it to app.json or app.config.js:

{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSMicrophoneUsageDescription": "This app uses your microphone so you can speak with the avatar."
      }
    }
  }
}

Android

Add microphone permission to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />

Hosted WebView fallback

If you do not need the package wrapper, you can embed the hosted avatar URL directly with react-native-webview:

import { WebView } from 'react-native-webview'
 
<WebView
  source={{ uri: 'https://avatarium.ai/a/YOUR_AVATAR_ID/voice' }}
  mediaPlaybackRequiresUserAction={false}
  allowsInlineMediaPlayback
  javaScriptEnabled
  style={{ flex: 1 }}
/>

Start with the hosted WebView fallback if you want the smallest possible mobile proof of concept. Use @avatarium/react-native when you want typed props and event helpers.

Next steps

ReactJavaScript / Widget