Put deterministic identity into the interface.

Start with a stable seed and namespace, then choose a browser SVG, React image component, Node.js PNG export, or manifest-backed group.

Browser example Node.js example

Vite or browser-bundled SVG.

The root entry point uses no Node.js built-ins. Generate a local SVG data URI and assign it to an image element.

import { avatarDataUri } from "agent-avatars";

const image = document.querySelector("#agent-avatar");
image.src = avatarDataUri("research-assistant", {
  namespace: "my-product/agents",
  theme: "light",
  size: 64,
});

The package test suite builds real browser consumers with Vite, webpack, and esbuild.

Next.js client component with SSR output.

A client component is still pre-rendered by Next.js. Keep seed and options stable so its server and browser markup agree.

"use client";

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

export function AgentBadge({ agent }) {
  return (
    <AgentAvatar
      seed={agent.id}
      size={48}
      options={{ namespace: "my-product/agents" }}
      alt={`${agent.name} avatar`}
    />
  );
}

See the React and SSR guide for fallback behavior, image URL props, and TypeScript module resolution.

Node.js SVG and PNG files.

SVG output comes from the root entry. Import the Node.js-only PNG subpath for byte generation and platform-size file sets.

import { writeFileSync } from "node:fs";
import { createHashAvatar } from "agent-avatars";
import { writeAvatarPngSet } from "agent-avatars/png";

const seed = "release-agent";
const options = { namespace: "my-product/agents", theme: "dark" };

writeFileSync("release-agent.svg", createHashAvatar(seed, options));

writeAvatarPngSet(seed, "./public/avatars", {
  ...options,
  sizes: [32, 64, 192, 200],
  baseName: "release-agent",
});

Fallback after a real image fails.

Do not replace a configured image preemptively. Track the source that failed, then render the deterministic component for that specific missing or broken value.

const [failedSrc, setFailedSrc] = useState();

return !src || failedSrc === src
  ? <AgentAvatar seed={agent.id} size={40} alt={`${agent.name} avatar`} />
  : <img src={src} width="40" height="40" alt={`${agent.name} avatar`}
      onError={() => setFailedSrc(src)} />;

A roster with durable assignments.

Create the group once, persist its manifest, and pass the manifest back before adding new agent identities.

import { createIdentitySet } from "agent-avatars";

const result = createIdentitySet(agentIds, {
  namespace: "my-product/agents",
  minimumShapeDistance: 4,
  minimumPaletteDistance: 20,
  distanceMode: "either",
  manifest: storedManifest,
});

await saveManifest(result.manifest);

Read the multi-agent identity guide before choosing distance thresholds.

Generate a real sample set.

Use the live workspace to change seeds, themes, palettes, group size, and separation before copying code or downloading assets.

Open generator API documentation