Skip to main content
Sign In
More

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: {
    // ...
  }
});
TypeScript

Icon Formats

The icon property accepts two formats:

Emoji

Use any emoji character directly:

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

FontAwesome Icons

Use FontAwesome icon names without the “fa” prefix:

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

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

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: "🚨" },
  // ...
});
TypeScript

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";

function myCustomRunHandler(options: MyOptions): RunConfig {
  async function run(c) {
    // Your run handler logic...
  }

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

Users can then use this directly:

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

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

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

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

Edit this page