View as Markdown Open in ChatGPT Open in Claude

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.

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`	No default	Required by the SDK's hooks and components.
`react-dom`Required	`>=18`	No default	Renders the SDK's components in the browser.
`@rive-app/react-webgl2`Required	`>=4.29.0`	No default	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`	No default	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 (
    <html>
      <body>
        <AvatarProvider config={config}>{children}</AvatarProvider>
      </body>
    </html>
  );
}

Then add <Avatar /> 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 (
    <div style={{ width: 400, height: 400 }}>
      <Avatar />
    </div>
  );
}

To control the session from your own UI, use the useAvatar 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 <button onClick={isIdle ? start : stop}>Talk</button>;
}

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.

Overview

AvatarProvider