Agent Avatars
HomeReact

React integration

Stable agent identity across client and server.

Render deterministic avatars through a typed React 18/19 component. The same seed and options produce the same local SVG data URI during server-side rendering and in the browser.

Use the componentTry a seed

One component, ordinary image props.

AgentAvatar renders an <img>. Pass a stable seed, display size, avatar options, accessible alternative text, and normal image attributes.

import { AgentAvatar } from "agent-avatars/react";

export function ResearchAssistant() {
  return (
    <AgentAvatar
      seed="research-assistant"
      size={64}
      options={{ namespace: "my-product/agents", theme: "dark" }}
      alt="Research assistant"
      className="agent-avatar"
    />
  );
}

Local avatars with SSR.

Generation is synchronous and local. Server-rendered markup contains the deterministic SVG data URI.

React 18 and 19

The optional peer dependency range is >=18 <20. Install React separately in your application.

Stable hydration input

Use the same stable seed, namespace, theme, and palette on the server and client.

Forwarded ref

The component forwards its ref to the underlying image element and accepts image attributes except direct src, width, and height control.

Keep uploaded images first.

Use an explicitly configured image while it loads successfully, and switch to a deterministic identity only when the source is missing or broken.

import { useState } from "react";
import { AgentAvatar } from "agent-avatars/react";

export function AgentImage({ src, agent }) {
  const [failedSrc, setFailedSrc] = useState();

  if (!src || failedSrc === src) {
    return (
      <AgentAvatar
        seed={agent.id ?? agent.name}
        size={40}
        options={{ namespace: "my-product/agents" }}
        alt={`${agent.name} avatar`}
      />
    );
  }

  return <img src={src} width="40" height="40" alt={`${agent.name} avatar`} onError={() => setFailedSrc(src)} />;
}

When a component wants a URL.

Some UI kits accept an avatar or src string instead of a React element. Generate a local SVG data URI through the root entry point.

import { avatarDataUri } from "agent-avatars";

const item = {
  title: agent.name,
  avatar: avatarDataUri(agent.id, {
    namespace: "my-product/agents",
    theme: "light",
    size: 40,
  }),
};

If your application has a Content Security Policy, allow data: for images before using SVG data URIs.

Typed subpath imports.

Declarations ship with the package. TypeScript consumers need TypeScript 4.7 or newer and Node16, NodeNext, or Bundler module resolution.

Seed selection

Prefer an immutable agent ID. Names work as a fallback, but renaming a display label will also change its avatar.

Build a complete agent roster.

Allocate a reusable set with explicit visual separation.

Identity-set guideAll APIs