Languages & Frameworks

React

Learn how to create real-time, stateful React applications with Rivet's actor model. The React integration provides intuitive hooks for managing actor connections and real-time updates.

Getting Started

See the React quickstart guide for getting started.

API Reference

`createRivetKit(endpoint?, options?)`

Creates the Rivet hooks for React integration.

import { actor, setup } from "rivetkit";

export const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, x: number) => {
      c.state.count += x;
      c.broadcast("newCount", c.state.count);
      return c.state.count;
    },
  },
});

export const registry = setup({
  use: { counter },
});

TypeScript

import { createRivetKit } from "@rivetkit/react";
import type { registry } from "./registry";

const { useActor } = createRivetKit<typeof registry>();

client.tsx

Parameters

endpoint: Optional endpoint URL (defaults to http://localhost:6420 or process.env.RIVET_ENDPOINT)
options: Optional configuration object

Returns

An object containing:

useActor: Hook for connecting to actors

`useActor(options)`

Hook that connects to an actor and manages the connection lifecycle.

import { actor, setup } from "rivetkit";

export const myActor = actor({
  state: { value: "" },
  actions: {
    getValue: (c) => c.state.value,
  },
});

export const registry = setup({
  use: { myActor },
});

TypeScript

import { createRivetKit } from "@rivetkit/react";
import type { registry } from "./registry";

const { useActor } = createRivetKit<typeof registry>();

function MyComponent() {
  const actor = useActor({
    name: "myActor",
    key: ["actor-id"],
    params: { userId: "123" },
    enabled: true
  });

  return <div>Status: {actor.connStatus}</div>;
}

component.tsx

Parameters

options: Object containing:
- name: The name of the actor type (string)
- key: Array of strings identifying the specific actor instance
- params: Optional parameters passed to the actor connection
- createWithInput: Optional input to pass to the actor on creation
- createInRegion: Optional region to create the actor in if does not exist
- enabled: Optional boolean to conditionally enable/disable the connection (default: true)

Returns

Actor object with the following properties:

connection: The actor connection for calling actions, or null if not connected
connStatus: The connection status ("idle", "connecting", "connected", or "disconnected")
error: Error object if the connection failed, or null
useEvent(eventName, handler): Method to subscribe to actor events

`actor.useEvent(eventName, handler)`

Subscribe to events emitted by the actor.

import { actor, setup } from "rivetkit";

export const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, x: number) => {
      c.state.count += x;
      c.broadcast("newCount", c.state.count);
      return c.state.count;
    },
  },
});

export const registry = setup({
  use: { counter },
});

TypeScript

import { createRivetKit } from "@rivetkit/react";
import type { registry } from "./registry";

const { useActor } = createRivetKit<typeof registry>();

function Counter() {
  const actor = useActor({ name: "counter", key: ["my-counter"] });

  actor.useEvent("newCount", (count: number) => {
    console.log("Count changed:", count);
  });

  return <div>Counter Component</div>;
}

component.tsx

Parameters

eventName: The name of the event to listen for (string)
handler: Function called when the event is emitted

Lifecycle

The event subscription is automatically managed:

Subscribes when the actor connects
Cleans up when the component unmounts or actor disconnects
Re-subscribes on reconnection

Advanced Patterns

Multiple Actors

Connect to multiple actors in a single component:

import { actor, setup } from "rivetkit";

export const userProfile = actor({
  state: { name: "", email: "" },
  actions: {
    update: (c, data: { name?: string; email?: string }) => {
      if (data.name) c.state.name = data.name;
      if (data.email) c.state.email = data.email;
      c.broadcast("profileUpdated", c.state);
    },
  },
});

export const notifications = actor({
  state: { items: [] as string[] },
  actions: {
    add: (c, message: string) => {
      c.state.items.push(message);
      c.broadcast("newNotification", message);
    },
  },
});

export const registry = setup({
  use: { userProfile, notifications },
});

TypeScript

import { createRivetKit } from "@rivetkit/react";
import type { registry } from "./registry";

const { useActor } = createRivetKit<typeof registry>();

function Dashboard() {
  const userProfile = useActor({
    name: "userProfile",
    key: ["user-123"]
  });

  const notifications = useActor({
    name: "notifications",
    key: ["user-123"]
  });

  userProfile.useEvent("profileUpdated", (profile) => {
    console.log("Profile updated:", profile);
  });

  notifications.useEvent("newNotification", (notification) => {
    console.log("New notification:", notification);
  });

  return (
    <div>
      <p>Profile Status: {userProfile.connStatus}</p>
      <p>Notifications Status: {notifications.connStatus}</p>
    </div>
  );
}

dashboard.tsx

Conditional Connections

Control when actors connect using the enabled option:

import { actor, setup } from "rivetkit";

export const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c) => ++c.state.count,
  },
});

export const registry = setup({
  use: { counter },
});

TypeScript

import { useState } from "react";
import { createRivetKit } from "@rivetkit/react";
import type { registry } from "./registry";

const { useActor } = createRivetKit<typeof registry>();

function ConditionalActor() {
  const [enabled, setEnabled] = useState(false);

  const counter = useActor({
    name: "counter",
    key: ["conditional"],
    enabled: enabled
  });

  return (
    <div>
      <button onClick={() => setEnabled(!enabled)}>
        {enabled ? "Disconnect" : "Connect"}
      </button>
      {counter.connStatus === "connected" && (
        <p>Connected!</p>
      )}
    </div>
  );
}

component.tsx

Real-time Collaboration

Build collaborative features with multiple event listeners:

import { actor, setup } from "rivetkit";

interface Position {
  x: number;
  y: number;
}

export const document = actor({
  state: {
    content: "",
    users: [] as string[]
  },
  actions: {
    updateContent: (c, newContent: string) => {
      c.state.content = newContent;
      c.broadcast("contentChanged", newContent);
    },
    moveCursor: (c, userId: string, position: Position) => {
      c.broadcast("cursorMoved", { userId, position });
    },
    join: (c, userId: string) => {
      c.state.users.push(userId);
      c.broadcast("userJoined", { userId });
    },
    leave: (c, userId: string) => {
      c.state.users = c.state.users.filter(u => u !== userId);
      c.broadcast("userLeft", { userId });
    },
  },
});

export const registry = setup({
  use: { document },
});

TypeScript

import { useState } from "react";
import { createRivetKit } from "@rivetkit/react";
import type { registry } from "./registry";

const { useActor } = createRivetKit<typeof registry>();

interface Position {
  x: number;
  y: number;
}

function CollaborativeEditor() {
  const [content, setContent] = useState("");
  const [cursors, setCursors] = useState<Record<string, Position>>({});

  const document = useActor({
    name: "document",
    key: ["doc-123"],
    params: { userId: "current-user" }
  });

  document.useEvent("contentChanged", (newContent: string) => {
    setContent(newContent);
  });

  document.useEvent("cursorMoved", ({ userId, position }: { userId: string; position: Position }) => {
    setCursors(prev => ({ ...prev, [userId]: position }));
  });

  document.useEvent("userJoined", ({ userId }: { userId: string }) => {
    console.log(`${userId} joined the document`);
  });

  document.useEvent("userLeft", ({ userId }: { userId: string }) => {
    setCursors(prev => {
      const { [userId]: _, ...rest } = prev;
      return rest;
    });
  });

  const updateContent = async (newContent: string) => {
    await document.connection?.updateContent(newContent);
  };

  return (
    <div>
      <textarea
        value={content}
        onChange={(e) => updateContent(e.target.value)}
      />
      <p>Active cursors: {Object.keys(cursors).length}</p>
    </div>
  );
}

editor.tsx

Authentication

Connect authenticated actors in React:

import { actor, setup } from "rivetkit";

export const protectedCounter = actor({
  state: { count: 0 },
  onBeforeConnect: (c, params: { authToken: string | null }) => {
    if (!params.authToken) {
      throw new Error("Authentication required");
    }
  },
  actions: {
    increment: (c) => ++c.state.count,
    getCount: (c) => c.state.count,
  },
});

export const registry = setup({
  use: { protectedCounter },
});

TypeScript

import { useState } from "react";
import { createRivetKit } from "@rivetkit/react";
import type { registry } from "./registry";

const { useActor } = createRivetKit<typeof registry>();

async function authenticateUser(): Promise<string> {
  return "jwt-token-here";
}

function AuthenticatedApp() {
  const [authToken, setAuthToken] = useState<string | null>(null);

  const counter = useActor({
    name: "protectedCounter",
    key: ["user-counter"],
    params: {
      authToken: authToken
    },
    enabled: !!authToken
  });

  const login = async () => {
    const token = await authenticateUser();
    setAuthToken(token);
  };

  if (!authToken) {
    return <button onClick={login}>Login</button>;
  }

  return (
    <div>
      <h1>Authenticated Counter</h1>
      <p>Status: {counter.connStatus}</p>
    </div>
  );
}

app.tsx

Learn more about authentication.

API Reference

Package: @rivetkit/react

See the full React API documentation at rivetkit.org/docs/actors/clients.

RivetKitProvider - React context provider
useActor - React hook for actor instances
createClient - Create a client
Client - Client type
ActorHandle - Handle for interacting with actors
ActorConn - Connection to actors