# Installation
Install one package, import one stylesheet, and you're ready to add an avatar.
## Authenticate to npm first
`@avatarfactory/react` is a **private package**. Add a `.npmrc` at your project
root with the token issued with your plan:
```ini
@avatarfactory:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${AVATARFACTORY_NPM_TOKEN}
```
Keep the token in your environment rather than in the file, so the `.npmrc` stays
safe to commit. Full setup, including CI: **[Get access](/docs/access)**.
## Install the package
Install the SDK along with the Rive React binding it renders through.
```bash
# npm
npm install @avatarfactory/react @rive-app/react-webgl2
# yarn
yarn add @avatarfactory/react @rive-app/react-webgl2
# pnpm
pnpm add @avatarfactory/react @rive-app/react-webgl2
```
> **Install the latest — don't pin a version.** The SDK is pre-1.0 and these docs
> track the current release, so a pinned version drifts out of sync with what is
> documented here. Run `npm ls @avatarfactory/react` to see what you are on.
## Import the stylesheet
Import the SDK's stylesheet once, at your app's entry point. **This is required** — without it, the avatar and its controls won't display correctly.
```tsx
// app/layout.tsx (Next.js App Router)
import "@avatarfactory/react/styles.css";
```
## Peer dependencies
The SDK declares four peers. You install two of them — React you already have, and
`@rive-app/webgl2` arrives on its own (see below).
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `react` **(required)** | `>=18` | — | Required by the SDK's hooks and components. |
| `react-dom` **(required)** | `>=18` | — | Renders the SDK's components in the browser. |
| `@rive-app/react-webgl2` **(required)** | `>=4.29.0` | — | The React binding, which provides the useRive hook the SDK renders through. This is the one you install. |
| `@rive-app/webgl2` **(required)** | `>=2.38.0` | — | The Rive WebGL2 runtime, which the SDK imports Fit, Alignment, Layout and EventType from. You do not install it yourself — see the note below. |
> **Why you don't install `@rive-app/webgl2` yourself.** The SDK imports from both
> Rive packages, so both are declared peers — but the runtime comes to you two ways
> without asking: `@rive-app/react-webgl2` depends on it, and npm and pnpm both
> install a package's peers automatically.
>
> **Adding it explicitly can hurt.** `@rive-app/react-webgl2` pins the runtime to an
> *exact* version, so installing `@rive-app/webgl2` yourself at a different version
> leaves two copies of the Rive wasm runtime in your tree — and `Fit` / `Layout`
> imported from one instance while `useRive` uses the other. Install the React
> binding and let the runtime follow it.
> The web SDK renders through **WebGL2**, not the older canvas runtime. If you are
> upgrading from a setup built on `@rive-app/react-canvas`, replace it with
> `@rive-app/react-webgl2` — leaving the canvas package installed will not satisfy
> the peer requirement.
## Next.js setup
The SDK runs in the browser, so any file that imports `AvatarProvider` must be a client component. The simplest approach is to mark your layout file with `"use client"` and set up the provider there.
```tsx
// app/layout.tsx
"use client";
import { AvatarProvider } from "@avatarfactory/react";
import "@avatarfactory/react/styles.css";
const config = {
// Fetches a session token from your backend on each connect.
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,
}: {
children: React.ReactNode;
}) {
return (
{children}
);
}
```
Then add `` anywhere in your app. It handles its own loading and connection state — just give it a sized container.
```tsx
// app/page.tsx
import { Avatar } from "@avatarfactory/react";
export default function MyPage() {
return (
);
}
```
To control the session from your own UI, use the [`useAvatar`](/docs/sdk/react/use-avatar) hook in any client component.
```tsx
// components/MyControls.tsx
"use client";
import { useAvatar } from "@avatarfactory/react";
export function MyControls() {
const { start, stop, isIdle } = useAvatar();
return ;
}
```
> `AvatarProvider`, `useAvatar`, and `useAvatarEvent` only work in client components. Mark any file that uses them with `"use client"`.
> You don't need a `@types` package — the SDK ships its own TypeScript types.