<!-- AvatarFactory Docs · https://avatarfactory.in/docs/sdk/react-native/overview · Full map: https://avatarfactory.in/llms.txt -->

# React Native SDK

Embed a real-time talking avatar in your iOS and Android app — live voice, lip-sync, and clean echo-cancelled audio.

The React Native SDK lets your users talk to an AI avatar inside your mobile app — or have the avatar speak text and audio you provide. You add a provider, a component, and a hook, and the SDK handles the live connection, the microphone, audio playback, and lip-sync.

If you've used the web SDK, the API is the same. The setup is a little different because mobile apps need native modules — see [Installation](/docs/sdk/react-native/installation) to get started.

> Built for **Expo** (SDK 50+) with a development build. The SDK includes a native audio module, so it doesn't run in Expo Go — [Installation](/docs/sdk/react-native/installation) covers the one-time setup.

## The parts you'll use

- **AvatarProvider**"
    description="Wrap your app once. It opens the connection and holds the session so every component below it can use the same avatar."
  />
- **Avatar**"
    description="Displays the character and animates its mouth in time with speech. Place it anywhere inside the provider and give it a size."
  />
- **useAvatar** — Control the avatar from your own UI: start and stop sessions, send text or audio, interrupt speech, and read live status.
- **useAvatarEvent** — Run code when something happens — the session starts, the avatar speaks, an error occurs — with cleanup handled for you.

## Four modes

Pick the mode that matches what you're building. You set it once in your config; everything else works the same.

          Mode
          What it does
          Best for

          call
          Two-way voice conversation in real time
          Mobile support agents, companions

          tts
          You send text, the avatar speaks it
          In-app narration, announcements

          audio
          You send audio, the avatar lip-syncs to it
          Custom voice providers, recordings

          player
          Plays a clip you made ahead of time — no server
          Onboarding screens, demos

See [Modes](/docs/sdk/react-native/modes) for a full walkthrough of each one.

## A few mobile differences

If you're coming from the web SDK, here's what changes on React Native:

- **Authentication is session-token only.** Mobile apps can't safely hold a secret key, so you always connect with `getSessionToken`. See [AvatarProvider](/docs/sdk/react-native/avatar-provider#authentication).
- **You style with `style`, not CSS.** Size and shape the avatar with a React Native `style` object — there's no stylesheet to import. See [Styling](/docs/sdk/react-native/styling).
- **The microphone needs a native permission.** Setup is automatic via the Expo plugin; see [Permissions](/docs/sdk/react-native/permissions).
- **Echo cancellation is built in,** so the avatar's voice doesn't leak back into the microphone during a call.

## Built with TypeScript

Every config object, hook return value, event, and error is fully typed. Import types directly from the package:

```tsx
import type {
  AvatarConfig,
  AvatarMode,
  AvatarSpeech,
  AvatarEventMap,
  UseAvatarResult,
} from "@avatarfactory/react-native";
```

## Where to go next

    Installation →
    Install the packages and set up Expo.

    AvatarProvider →
    Connect, authenticate, and configure.

    useAvatar →
    Start, stop, speak, and read live state.

    Permissions →
    Microphone access on iOS and Android.