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:

<CodeSnippet file="examples/docs/actors-appearance/config-basic.ts" />

Icon Formats

The icon property accepts two formats:

Emoji

Use any emoji character directly:

<CodeSnippet file="examples/docs/actors-appearance/icon-emoji.ts" />

FontAwesome Icons

Use FontAwesome icon names without the "fa" prefix:

<CodeSnippet file="examples/docs/actors-appearance/icon-fontawesome.ts" />

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:

<CodeSnippet file="examples/docs/actors-appearance/examples-patterns.ts" />

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:

<CodeSnippet file="examples/docs/actors-appearance/run-handler-metadata.ts" />

Users can then use this directly:

<CodeSnippet file="examples/docs/actors-appearance/run-handler-usage.ts" />

This run-handler metadata is currently applied through the registry and serverless metadata paths. The native runtime and inspector config read the actor's options.name and options.icon directly, so set those explicitly if you need the name or icon to appear everywhere.

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

<CodeSnippet file="examples/docs/actors-appearance/run-handler-override.ts" />

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