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

# React SDK

Embed a real-time talking avatar in your web app with one provider, one component, and one hook.

The React SDK lets your users talk to an AI avatar — or have the avatar speak text and audio you provide — directly in the browser. You add three things to your app and the SDK takes care of the live connection, the microphone, audio playback, and lip-sync.

If you haven't installed it yet, start with [Installation](/docs/sdk/react/installation), or follow the [Quickstart](/docs/quickstart) for a step-by-step 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. Drop 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
          Support agents, virtual companions

          tts
          You send text, the avatar speaks it
          Narration, scripted 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
          Landing pages, demos, cached replies

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

## What else is in the box

Beyond the three building blocks, the SDK ships a set of things you would
otherwise build yourself. Each is off or sensibly defaulted, and each can be
replaced with your own UI.

    Transcript & captions →
    A live, word-timed record of the conversation, with a built-in caption overlay.

    Camera perception →
    Let the avatar see. Opt-in, opened just-in-time, held in memory only.

    Push to talk →
    Hand turn-ending to the user for noisy rooms and shared spaces.

    Health & status banner →
    Blame-resolved connectivity warnings, so you know whose problem it is.

    Greetings & ringback →
    An opening line, and a connect tone that makes it feel like placing a call.

    Bring your own keys →
    Run the voice or the model on your own OpenAI, Anthropic, Google, ElevenLabs, or Inworld account.

## Built with TypeScript

Every config object, hook return value, event, and error is fully typed, so you get autocomplete and type-checking as you build. Import types directly from the package:

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

TypeScript is optional, but recommended — the autocomplete on the config object alone saves a lot of trips to these docs.

## Where to go next

    Installation →
    Install the package and set up Next.js.

    AvatarProvider →
    Connect, authenticate, and configure.

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

    Types →
    The full TypeScript reference.