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 component Try 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"
    />
  );
}

SSR without an avatar request.

Generation is synchronous and local. Server-rendered markup already contains the deterministic SVG data URI, so the identity does not wait for an external avatar API.

React 18 and 19

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

Stable hydration input

Use the same seed, namespace, theme, and palette on the server and client. Do not derive the seed from a browser-only random value.

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.

Private identifiers

Never render a sensitive identifier directly in browser code. Use the server-side HMAC workflow.

Build a complete agent roster.

When individual deterministic hashes are not enough, allocate a reusable set with explicit visual separation.

Identity-set guide All APIs