By Zeeli

Agent Avatar

Animated avatars for agents and sub-agents. characters, four states each, in a single web component with no dependencies.

Install

Install from npm, then import it once. Importing it registers the <agent-avatar> element.

pnpm add agent-avatar

import 'agent-avatar';

Usage

HTML

<agent-avatar variant="teddy" state="working" size="40"></agent-avatar>

React 19

import 'agent-avatar';

export function AgentRow({ agent }) {
  return <agent-avatar variant={agent.avatar} state={agent.status} size={28} />;
}

Reading the catalog

import { CHARACTERS, SETS, STATES, VARIANTS } from 'agent-avatar';

VARIANTS;             // ['mochi', 'byte', ...]
CHARACTERS.rex.title; // 'Rex'
SETS.map((s) => s.title);

Playground

Pick a character, a state and a size. The snippet updates as you go.

Character

State

Size 180px

In context

API

Attribute	Values	Default
`variant`		`mochi`
`state`	`idle` · `working` · `attention` · `done`	`idle`
`size`	Number in px, or any CSS length. Numbers at 32 or below turn on lite mode.	`96px`
`label`	Accessible label read by screen readers.	`Agent <state>`

Exports

`AgentAvatar`	The element class, already registered as `<agent-avatar>`.
`VARIANTS`	Every variant name, in catalog order.
`CHARACTERS`	Metadata per variant: `title`, `set`, `description`.
`SETS`	The catalog groups: Abstract, Characters, Party crew, Wild bunch, Edgy crew.
`STATES`	The four states.

States

Each state has its own colour, face, motion and corner badge, so it reads even at 16px.

State	Colour	Meaning
`idle`	Lavender	Waiting for work. Blinks and breathes.
`working`	Blue, typing dots	Busy. Each character uses its prop.
`attention`	Orange, `!` badge	Needs input or approval from you.
`done`	Green, check badge	Finished. Celebrates with sparkles.

Performance

Compositor motion	Bounce, squash, shadow, badges and sparkles only animate `transform` and `opacity` on HTML layers.
No filters	Glows and highlights are baked gradients. No SVG blur runs per frame.
Active state only	Hidden states run no animations.
Offscreen pause	One shared IntersectionObserver pauses avatars that scroll out of view.
Lite mode	At `size` 32 or below, idle is static and other states keep one body motion.
Shared resources	One stylesheet per variant and a cached template for markup.

Headless Chrome benchmark: 300 avatars at 28px, 50 at 64px and 20 at 96px all hold 60fps.