zeroweight-renderer-react

React hooks and components for the ZeroWeight avatar renderer. Drop-in LiveKit-powered avatar sessions for React and Next.js.

Installation

npm install zeroweight-renderer-react zeroweight-renderer

Peer Dependencies

The following are required in your project:

npm install react react-dom @livekit/components-react @livekit/components-styles livekit-client lucide-react

LiveKit packages are optional if you only use the renderer without voice chat.

Quick Start

Drop-in Component (Simplest)

import { LiveKitAvatarSession } from "zeroweight-renderer-react";

function App() {
  return (
    <LiveKitAvatarSession
      avatarId="your-avatar-id"
      livekitUrl="wss://your-livekit-server.example.com"
      api={{
        getBundle: (avatarId) =>
          fetch(`/api/avatars/bundle/${avatarId}`).then((r) => r.json()),
        getLiveKitToken: (avatarId, userName) =>
          fetch(
            `/api/livekit/token?avatar_id=${avatarId}&name=${userName}`,
          ).then((r) => r.json()),
      }}
    />
  );
}

This renders a full avatar session with canvas, controls, status badge, and LiveKit voice chat — all wired up automatically.

Custom UI (Full Control)

import {
  useAvatarSession,
  LiveKitAvatarProvider,
} from "zeroweight-renderer-react";
import { LiveKitRoom } from "@livekit/components-react";

function CustomAvatar() {
  const session = useAvatarSession({
    avatarId: "your-avatar-id",
    livekitUrl: "wss://...",
    api: { getBundle, getLiveKitToken },
  });

  return (
    <div>
      {/* Canvas container — renderer injects <canvas> here */}
      <div ref={session.containerRef} style={{ width: 640, height: 480 }} />

      {/* Your own UI */}
      <p>State: {session.rendererState}</p>
      <button onClick={session.connect}>Connect</button>
      <button onClick={session.disconnect}>Disconnect</button>
      <button onClick={() => session.runAction("wave_hand")}>Wave</button>

      {/* LiveKit room for voice (hidden) */}
      {session.token && (
        <LiveKitRoom
          serverUrl={session.livekitUrl}
          token={session.token}
          connect
          audio
          onConnected={session.markConnected}
          onDisconnected={session.disconnect}
        >
          <LiveKitAvatarProvider session={session} />
        </LiveKitRoom>
      )}
    </div>
  );
}

API

ZeroWeightApi Interface

You provide your own backend integration via this interface:

interface ZeroWeightApi {
  getBundle: (avatarId: string) => Promise<{ payload: any }>;
  getLiveKitToken: (
    avatarId: string,
    userName: string,
  ) => Promise<{ token: string }>;
}

useAvatarSession(config)

The core React hook. Manages the renderer lifecycle and returns reactive state + imperative methods.

Config:

| Prop | Type | Required | Description | | ------------------- | --------------- | -------- | ---------------------------------------------- | | avatarId | string | ✅ | Avatar ID to load | | api | ZeroWeightApi | ✅ | Your API implementation | | livekitUrl | string | – | LiveKit server URL | | sessionDuration | number | – | Session limit in seconds (default: 120) | | inactivityTimeout | number | – | Auto-disconnect timeout in ms (default: 30000) |

Returns:

| Property | Type | Description | | --------------- | ----------- | -------------------------------------------------------- | | containerRef | RefObject | Attach to a <div> — renderer creates <canvas> inside | | rendererState | string | "idle" | "loading" | "ready" | "error" | | isEngineReady | boolean | true when renderer is ready | | isConnected | boolean | LiveKit connection status | | connect() | function | Start voice session | | disconnect() | function | End voice session | | runAction(id) | function | Trigger an avatar action | | toggleMic() | function | Toggle microphone mute | | setVolume(v) | function | Set audio volume (0–1) |

Components

| Component | Description | | ----------------------- | -------------------------------------------------- | | LiveKitAvatarSession | Full drop-in: canvas + controls + LiveKit | | AvatarCanvas | Canvas container with loading overlay | | AvatarControls | Default mic/connect buttons | | AvatarStatusBadge | Online/offline status indicator | | LiveKitAvatarProvider | LiveKit ↔ renderer bridge (inside <LiveKitRoom>) |

All components accept a session prop from useAvatarSession().

Integration Example

Adapting an existing API service:

import { api } from "./my-api";
import type { ZeroWeightApi } from "zeroweight-renderer-react";

const zeroWeightApi: ZeroWeightApi = {
  getBundle: (avatarId) => api.getBundle(avatarId),
  getLiveKitToken: (_avatarId, userName) => api.getToken(userName),
};

Build from Source

git clone <repo-url>
cd zeroweight-renderer-react
npm install
npm run build

Output in dist/:

• zeroweight-renderer-react.es.js — ES module (14 KB)
• zeroweight-renderer-react.cjs.js — CommonJS (11 KB)
• *.d.ts — TypeScript declarations

License

MIT