Icons & Names

Customize actors with display names and icons for the Rivet inspector and dashboard.

Icons & Names

Actors can be customized with a display name and icon that appear in the Rivet inspector & dashboard. This helps identify actors at a glance when managing your application.

Configuration

Set the name and icon properties in your actor’s options:

import { actor } from "rivetkit";

const chatRoom = actor({
  options: {
    name: "Chat Room",    // Human-friendly display name
    icon: "comments",     // FontAwesome icon name
  },
  state: { messages: [] },
  actions: {
    // ...
  }
});

Icon Formats

The icon property accepts two formats:

Emoji

Use any emoji character directly:

import { actor } from "rivetkit";

const notificationService = actor({
  options: {
    name: "Notifications",
    icon: "🔔",
  },
  // ...
});

FontAwesome Icons

Use FontAwesome icon names without the “fa” prefix:

import { actor } from "rivetkit";

const gameServer = actor({
  options: {
    name: "Game Server",
    icon: "gamepad",
  },
  // ...
});

const analyticsWorker = actor({
  options: {
    name: "Analytics",
    icon: "chart-line",
  },
  // ...
});

Default Behavior

If no icon is specified, actors display the default actor icon. If no name is specified, the actor’s registry key (e.g., chatRoom, gameServer) is displayed instead.

Examples

Here are some common patterns:

import { actor } from "rivetkit";

// Chat/messaging actors
const chatRoom = actor({
  options: { name: "Chat Room", icon: "comments" },
  // ...
});

// Game-related actors
const matchmaker = actor({
  options: { name: "Matchmaker", icon: "users" },
  // ...
});

const gameSession = actor({
  options: { name: "Game Session", icon: "gamepad" },
  // ...
});

// Data processing actors
const dataProcessor = actor({
  options: { name: "Data Processor", icon: "microchip" },
  // ...
});

// Using emojis for quick identification
const alertService = actor({
  options: { name: "Alerts", icon: "🚨" },
  // ...
});

Advanced: Run Handler Metadata

For library developers creating reusable run handlers, you can bundle icon and name metadata directly with the run property. This allows libraries to provide sensible defaults without requiring users to configure them manually.

Instead of returning a function from your run handler factory, return an object with name, icon, and run:

import type { RunConfig } from "rivetkit";

type MyOptions = {
  mode?: "safe" | "fast";
};

function myCustomRunHandler(_options: MyOptions): RunConfig {
  const run: RunConfig["run"] = async (_c) => {
    // Your run handler logic...
  };

  return {
    name: "My Custom Handler",
    icon: "bolt",
    run,
  };
}

Users can then use this directly:

import { actor } from "rivetkit";

const myCustomRunHandler = (_options: Record<string, unknown>) => ({
  name: "My Custom Handler",
  icon: "bolt",
  run: async () => {},
});

const myActor = actor({
  run: myCustomRunHandler({ /* options */ }),
  // Automatically gets "My Custom Handler" name and "bolt" icon
});

Actor-level options.name and options.icon always take precedence, allowing users to override library defaults:

import { actor } from "rivetkit";

const myCustomRunHandler = (_options: Record<string, unknown>) => ({
  name: "My Custom Handler",
  icon: "bolt",
  run: async () => {},
});

const myActor = actor({
  options: {
    name: "Custom Name",  // Overrides "My Custom Handler"
    icon: "rocket",       // Overrides "bolt"
  },
  run: myCustomRunHandler({ /* options */ }),
});

The built-in workflow() helper uses this pattern to automatically display the workflow icon for workflow-based actors.