# Bot avatars
> Plush, furry 3D faces for AI agents that look around, blink, hop at work and doze off, drawn on a plain canvas.
Avatars for the agents in an app: eighteen soft bodies, from a clover to a little robot, each with two painted eyes. They look around and follow the pointer, blink, and every few seconds hop, spin or flip; at work they bounce on a beat and beam as they land, and asleep they bow with their eyes shut. Five finishes, from fur to glossy plastic, hats, glasses and a dozen dials, all rendered by a small software renderer on a 2D canvas, with no WebGL.
A React component by Bruno Delorence: https://brunodelorence.com/components/bot-avatars. MIT License, Copyright (c) 2026 Bruno Delorence.
Category: AI.
## Anatomy
1. **Avatar box**: The `size` it takes in the layout: a square that sits in a row like an icon. With `label` it is an image of that name; without it, decorative.
2. **Canvas**: Half as large again as the box, more of it above, so hops and hats have room; it overflows the box and ignores the pointer.
3. **Body**: The plush cushion inflated from the type’s outline, furred along its edge with `fabric` or `crisp` shading.
4. **Eyes**: Two ovals painted in `ink` on the face: they slide to look, flatten to blink and curve to beam or sleep.
5. **Glasses**: Round or square frames ringed around the eyes and bridged, sitting just off the face.
6. **Antenna**: A hard part some bodies carry (`droid`, `mech`, `alien`): a glossy stem and ball in a darker shade.
7. **Ear disc**: A flattened disc on each side of the `droid`’s head, in the same glossy finish as the antenna.
## When to use
- A face for each AI agent or assistant in an app: a list of bots, a chat reply, a task card, an empty state.
- Showing what an agent is doing at a glance: `idle` looks around, `working` hops on a beat while it thinks, `sleeping` dozes.
- Telling several bots apart: eighteen bodies, five finishes, hats, glasses and any colour, with a `seed` so neighbours don’t move in step.
- A friendly, tactile touch in a product that talks: it follows the pointer and leaps when poked.
## When not to use
- A person. Use a photo or an initials avatar; a plush creature reads as a bot.
- A precise status (queued, failed, 42 % done). Use a badge, a spinner or a progress bar beside it; the avatar’s mood is only a hint.
- Dense tables with hundreds of rows. Use a static icon or a single still frame: each avatar is a canvas, and many live ones cost frames.
- Serious or formal tools (finance, legal, health), where a playful mascot undercuts trust. Use a plain logo mark.
- Below about 24 px, where the fur and the eyes blur into a smudge. Use a coloured dot or an icon.
## Installation
Install it with the shadcn CLI, into components/bot-avatars of any React project:
```sh
npx shadcn@latest add https://brunodelorence.com/r/bot-avatars.json
```
Or copy all the source files below into one folder of your project. Either way it needs React 19 and a bundler with CSS Modules (Next.js, Vite).
It has a dark colour scheme. Its colours are CSS light-dark() pairs, kept inside @supports so that builds which rewrite light-dark() for older browsers leave them alone: it follows your page’s color-scheme (light unless the page sets one) or its colorScheme prop, with nothing to configure. Browsers without light-dark() show it light.
## Usage
```tsx
import { BotAvatar } from './bot-avatar';
export function AgentRow({ busy }: { busy: boolean }) {
return (
Research aide
);
}
```
## States
- **Idle**: At rest it faces front, eyes open; live, it looks around, blinks and does a trick every few seconds.
- **Working**: `state="working"` hops on a beat and beams as it lands. Shown live: its still pose is idle’s.
- **Sleeping**: `state="sleeping"`: bowed, eyes shut in arcs, breathing slowly.
- **Sizes**: 96, 64, 36 and 32 px: the same drawing, the fur scaled with it.
- **Colour and ink**: Any `color` for the body and any `ink` for the eyes; the light and the tuning still apply.
- **Fur length**: `furLength` 0, 1 and 2, left to right: from a short velvet to a long shag.
- **Lit**: Strong `backLight`, a `sheen` and a deeper `shadow`, for a dark stage.
## How it works
- Each body is a flat outline written as a signed distance function. A grid laid over it is pulled onto the outline at the edge, then lifted into a cushion: the height is the square root of a membrane stretched over the outline and pushed out from behind (a Poisson problem solved once by over-relaxation), so it rounds off steeply at the seam and has no folds where lobes meet. The back is its mirror; the two sheets share the outline.
- Every frame the two sheets are squashed, turned and lifted into place and filled triangle by triangle into a depth buffer, which keeps each pixel’s normal and its spot on the face. Antennas, ear discs, hats and glasses are spheres, cones and tubes found by casting a ray through each pixel of their box into the same buffer.
- Each covered pixel is then lit once: a key light from the upper left with a soft wrap, the lit side washed paler, a back light round the rim and an optional sheen. The colour tuning (brightness and saturation) comes after the light, and saturates the shade more than the light, so shadows deepen instead of turning grey.
- The fur: a few thousand roots scattered evenly over the surface once, each with its own length, shade and lean. Those on the visible side grow along the turned normal and are drawn as fading lines over the lit body; along the outline they stand out against the background, which makes the soft fuzzy edge. Fine noise fixed to the surface breaks up the colour and turns with it. Plastic, smooth and flat skip the fur and are drawn at twice the size, then scaled down, for clean edges.
- The eyes are painted from the face’s own coordinates, so they turn with the body; they slide across the face to look, flatten to a dash to blink, and become arcs to beam (^ ^) or sleep (‿ ‿).
- Behaviour is a spring for the gaze and the eyes plus short timelines for tricks: a crouch, a parabolic hop that stretches on the way up and down, a full turn or flip in the air, and a landing squash that rings out. Squash and stretch keep the volume. Idle avatars look around and do a trick every few seconds; working ones hop on a beat; sleeping ones breathe slowly with a bow. Poking one makes it leap and land beaming.
- All avatars on a page share one animation frame loop, and each draws only while on screen in a visible tab. The pointer is read once per move for all of them; each looks at it while it moves, then goes back to looking around.
## API reference
- **type** (`'clover' | 'flower' | 'star' | 'ghost' | 'mech' | 'circle' | 'hexagon' | 'square' | 'triangle' | 'blob' | 'drop' | 'droid' | 'alien' | 'cat' | 'cloud' | 'pill' | 'pebble' | 'puddle'`, default `'clover'`): The body. The props down to label are the avatar’s (BotAvatar); the last three are the showcase’s (BotAvatars).
- **size** (`number`, default `64`): The box it takes in the layout, in px. The drawing overflows it, a quarter at the sides and more above, so hops and hats have room.
- **state** (`'idle' | 'working' | 'sleeping'`, default `'idle'`): Idle looks around and does a trick now and then; working hops on a beat; sleeping bows with its eyes shut and breathes slowly.
- **shading** (`'fabric' | 'plastic' | 'crisp' | 'smooth' | 'flat'`, default `'fabric'`): The finish: fur, glossy plastic, a short crisp pile, smooth velvet, or flat colour.
- **hat** (`'none' | 'beret' | 'beanie' | 'party' | 'crown'`, default `'none'`): Something to wear on top.
- **glasses** (`'none' | 'round' | 'square'`, default `'none'`): Frames around the eyes.
- **color** (`string`): The body’s colour, as hex, before light and tuning (the tuning deepens it); each type has its own without it.
- **ink** (`string`, default `'#1f1b2e'`): The eyes’ colour, used as it is.
- **furLength** (`number`, default `1`): Strand length, 0 to 2.
- **brightness** (`number`, default `120`): Brightness of the colour, in %.
- **saturation** (`number`, default `159`): Saturation of the colour, in %.
- **shadow** (`number`, default `115`): How deep the shading goes, in %.
- **backLight** (`number`, default `60`): Light round the rim from behind, 0 to 100 %.
- **sheen** (`number`, default `0`): A soft highlight from the key light, 0 to 100 %.
- **depth** (`number`, default `65`): Thickness of the body, 0 to 100 %.
- **edgeFuzz** (`number`, default `90`): How far the fur fluffs out along the outline, 0 to 100 %.
- **speed** (`number`, default `1`): Speed of every motion, as a multiple.
- **paused** (`boolean`, default `false`): Holds it still, facing front, in its state’s resting pose.
- **interactive** (`boolean`, default `true`): Looks at the pointer while it moves, and leaps when poked (clicked or tapped).
- **seed** (`number`): Varies its habits, so avatars side by side don’t move in step.
- **label** (`string`): A name for screen readers (role img); without it the avatar is decorative and hidden from them.
- **autoplay** (`boolean`, default `true`): Showcase: its avatars live on their own and the chat plays while on screen; false holds them still.
- **colorScheme** (`'light' | 'dark' | 'system'`): Showcase: its colours, light, dark, or the reader’s system setting. Without it the showcase follows the page’s color-scheme, which is light unless the page sets one. The avatars look the same on both.
- **className** (`string`): Extra class for the root.
## Accessibility
- An avatar is decorative (aria-hidden) unless it has a label, which makes it an image with that name. Next to a name, as in a list of bots, leave it decorative.
- The list says each bot’s state in words for screen readers (Idle, Working, Sleeping), not only by how the avatar moves.
- The chat’s reply is a polite live region, busy while the bot thinks and streams, so it is read once when complete.
- The playground’s options are radio groups (arrow keys, Home and End move the choice), the dials are native range inputs with their values spoken, the swatches are toggle buttons with names, and Play is a toggle button. Every control has a visible focus ring.
- Under reduced motion the avatars hold their resting pose (and still change with their state and options), the reply appears at once and Thinking… does not shimmer. They also stop off screen and in hidden tabs.
## Source
### bot-avatars/bot-avatars.tsx
```tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.
'use client';
import { useEffect, useId, useRef, useState, type KeyboardEvent } from 'react';
import { BotAvatar, type BotAvatarProps } from './bot-avatar';
import type { State } from './brain';
import type { Glasses, Hat, Shading } from './render';
import { SHAPE_NAMES, type ShapeName } from './shapes';
import { useAutoplay } from './use-autoplay';
import styles from './bot-avatars.module.css';
/*
* Bot avatars: plush, furry 3D faces for AI agents, drawn on a plain 2D canvas (no WebGL). This
* file is the showcase around the avatar itself (bot-avatar.tsx):
*
* - A row of four, living on their own: looking around, blinking, hopping and spinning now and
* then, and following the pointer while it moves. Poke one and it leaps.
* - Two scenes from an agent app: a list of bots, one idle, one at work, one asleep; and a chat,
* where the bot works while it thinks, then settles as its answer streams in word by word.
* - A playground with every option (eighteen bodies, three states, three sizes, five finishes,
* hats, glasses, fur, colour, ink and light), and the code for what it shows.
*
* Colours are light-dark() tokens on the root, so the showcase follows the page's color-scheme or
* the colorScheme prop; the avatars look the same on both.
*/
const TITLE = (s: string) => s[0].toUpperCase() + s.slice(1);
const STATES: State[] = ['idle', 'working', 'sleeping'];
const SIZES = [96, 64, 32];
const SHADINGS: Shading[] = ['fabric', 'plastic', 'crisp', 'smooth', 'flat'];
const HATS: Hat[] = ['none', 'beret', 'beanie', 'party', 'crown'];
const GLASSES: Glasses[] = ['none', 'round', 'square'];
/**
* Body colours: the swatch shows the colour as it reads on the lit face; the value is the colour
* before light and tuning, which is what the avatar takes.
*/
const COLORS = [
{ name: 'Sky', swatch: '#41c4ff', value: '#68badf' },
{ name: 'Mint', swatch: '#2fcb7a', value: '#5abb88' },
{ name: 'Orchid', swatch: '#dc48ff', value: '#b458ca' },
{ name: 'Ocean', swatch: '#35b8ff', value: '#5caeda' },
{ name: 'Snow', swatch: '#f4f2fa', value: '#f2f0f5' },
];
/** Eye colours, used as they are. */
const INKS = [
{ name: 'Night', swatch: '#1f1b2e', value: '#1f1b2e' },
{ name: 'Chalk', swatch: '#f6f4f0', value: '#f6f4f0' },
{ name: 'Ocean', swatch: '#35b8ff', value: '#35b8ff' },
{ name: 'Orchid', swatch: '#dc48ff', value: '#dc48ff' },
];
const REPLY =
'Three things stood out: the pilot starts in May, legal wants the data terms by Friday, and the budget stays where it was.';
const QUESTION = 'Could you sum up the notes from Tuesday’s call?';
type Settings = {
type: ShapeName;
state: State;
size: number;
shading: Shading;
hat: Hat;
glasses: Glasses;
furLength: number;
color: string | undefined;
brightness: number;
saturation: number;
ink: string;
shadow: number;
backLight: number;
sheen: number;
depth: number;
edgeFuzz: number;
speed: number;
};
const DEFAULTS: Settings = {
type: 'clover',
state: 'idle',
size: 96,
shading: 'fabric',
hat: 'none',
glasses: 'none',
furLength: 100,
color: undefined,
brightness: 120,
saturation: 159,
ink: '#1f1b2e',
shadow: 115,
backLight: 60,
sheen: 0,
depth: 65,
edgeFuzz: 90,
speed: 1,
};
export function BotAvatars({
autoplay = true,
colorScheme,
className = '',
}: {
/** The showcase's avatars live on their own and the chat plays while on screen; false holds them still. */
autoplay?: boolean;
/** Light or dark colours, or the reader's ('system'); without it, the page's color-scheme. */
colorScheme?: 'light' | 'dark' | 'system';
className?: string;
}) {
const still = !autoplay;
return (
);
}
/** How long the bot thinks, then how long each word takes to come in, then how long it rests. */
const THINK = 2600;
const WORD = 70;
const HOLD = 1700;
function Chat({ still }: { still: boolean }) {
const { ref, playing } = useAutoplay(6000);
const words = REPLY.split(' ');
// -1 while thinking, then how many words are in.
const [shown, setShown] = useState(words.length);
const run = playing && !still;
useEffect(() => {
if (!run) {
setShown(words.length);
return;
}
let timer = 0;
let n = -1;
const next = () => {
if (n < 0) {
setShown(-1);
n = 0;
timer = window.setTimeout(next, THINK);
} else if (n < words.length) {
n++;
setShown(n);
timer = window.setTimeout(next, n === words.length ? HOLD + words.length * 6 : WORD);
} else {
n = -1;
next();
}
};
next();
return () => window.clearTimeout(timer);
}, [run, words.length]);
const thinking = shown < 0;
return (
{QUESTION}
{/* The full answer keeps the space, so nothing below jumps as it streams. */}