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

# Quickstart

Get a talking avatar running in your React app in four steps.

This guide uses the React (web) SDK. Building a mobile app? Follow the [React Native quickstart](/docs/sdk/react-native/installation) instead.

## Installation

### Step 1 — Install the package

The SDK is a **private package**, so authenticate to npm first. Add a `.npmrc` at
your project root with the token that came with your plan — see
[Get access](/docs/access) if you don't have one yet.

```ini
@avatarfactory:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${AVATARFACTORY_NPM_TOKEN}
```

Then install the SDK and the Rive React binding it renders through.

```bash
npm install @avatarfactory/react @rive-app/react-webgl2
```

Then import the stylesheet once, at your app's entry point. **The avatar won't display correctly without it.**

```tsx
// app/layout.tsx
import "@avatarfactory/react/styles.css";
```

### Step 2 — Wrap your app with AvatarProvider

`AvatarProvider` opens the connection and holds the session. Add it once, near the top of your app.

To connect, the SDK needs a session token. You provide a `getSessionToken` function that fetches one from your backend. The SDK calls it whenever it connects, so your secret API key stays on the server and never reaches the browser.

```tsx
// app/layout.tsx
"use client";
import { AvatarProvider } from "@avatarfactory/react";
import "@avatarfactory/react/styles.css";

const config = {
  getSessionToken: async () => {
    const res = await fetch("/api/avatar-token");
    const { sessionToken } = await res.json();
    return sessionToken;
  },
  mode: "call",
  avatar: {
    avatarId: "default",
  },
};

export default function RootLayout({ children }) {
  return (
    <AvatarProvider config={config}>
      {children}
    </AvatarProvider>
  );
}
```

> Leave `avatarId` as `"default"` to use our public demo avatar — it works out of the box, so you can finish this guide without any setup. When you're ready for your own avatar, **[publish one in the Platform](/docs/platform/avatars)** and swap in its ID. You'll set up the `/api/avatar-token` endpoint next — see **[Authentication](/docs/authentication)** for ready-to-copy server examples (Node, Next.js, Python, cURL).

### Step 3 — Add the Avatar component

Place `` anywhere inside the provider. **Give its parent a width and height** — the avatar fills its container, so without a size it won't be visible.

```tsx
import { Avatar } from "@avatarfactory/react";

export default function MyPage() {
  return (
    <div style={{ width: 400, height: 400 }}>
      <Avatar />
    </div>
  );
}
```

### Step 4 — Turn on the built-in controls

In `call` mode the SDK can render its own start and stop buttons, so you don't have to build any control UI. They're off by default — turn them on with `controls.enabled`.

```tsx
const config = {
  getSessionToken: async () => fetchSessionToken(),
  mode: "call",
  avatar: { avatarId: "default" },
  controls: { enabled: true }, // show the built-in start/stop buttons
};
```

## You're live

Run your app, click start, and speak to your avatar. That's the full setup.

> In `call` mode, the browser asks for microphone permission when the session starts. That's expected — the avatar needs to hear the user.

> **Want your own buttons instead?** Leave `controls.enabled` off and use the [`useAvatar`](/docs/sdk/react/use-avatar) hook to call `start()` and `stop()` and read live status like `isConnected`, `isSpeaking`, and `isListening`.

## What's next

    AvatarProvider →
    Every config option explained.

    Modes →
    call, tts, audio — pick the right one.

    useAvatar →
    Control the avatar from your own UI.

    Events →
    React to start, stop, speaking, and errors.