Bot avatars

Animated faces for AI agents: twenty-one shapes, three states, five materials.

Clover

Flower

Triangle

Square

Blob

Ghost

Circle

Drop

Star

Droid

Mech

Alien

Hexagon

Cat

Cloud

Pill

Pebble

Puddle

Dot

Planet

Spark

dot

dot, flat

three dots, working

planet

spark

fabric

plastic

crisp

smooth

flat

Playground

<script>
  import { BotAvatar } from 'runeglow/bot-avatars';
</script>

<BotAvatar size={124} />

Install

pnpm add runeglow

Or copy just this library’s source into your project, with the shadcn-svelte CLI:

npx shadcn-svelte@latest add https://runeglow.dev/r/bot-avatars.json
import { BotAvatar } from 'runeglow/bot-avatars';

Usage

One element. It lays out at its size and keeps room around itself to hop and flip.

<script>
  import { BotAvatar } from 'runeglow/bot-avatars';
</script>

<BotAvatar type="clover" />

Drive state from what the agent is really doing.

<script>
  import { BotAvatar } from 'runeglow/bot-avatars';

  let { busy } = $props();
</script>

<BotAvatar type="cat" state={busy ? 'working' : 'default'} size={40} />

Change the material and dress it up.

<BotAvatar
  type="ghost"
  shading="plastic"
  hat="party"
  glasses="round"
  accessoryColor="#c8323c"
/>

Avatars in a row each keep their own timing unless you give them the same seed.

<!-- The same seed keeps a row blinking in step; leave it out and each goes its own way. -->
<BotAvatar type="star" seed={0.3} />
<BotAvatar type="drop" seed={0.3} />

dot has no face, so it works as a plain orb, or three in a row as a typing indicator.

<!-- A typing indicator: three bare dots, each on its own beat. -->
<span class="typing">
  <BotAvatar type="dot" state="working" size={22} seed={0.1} />
  <BotAvatar type="dot" state="working" size={22} seed={0.4} />
  <BotAvatar type="dot" state="working" size={22} seed={0.7} />
</span>

Props

Prop Type Default Description
type BotAvatarType 'clover' The body shape, one of twenty-one. Each has its own colour and face position.
state 'default' | 'working' | 'sleeping' 'default' What the bot is doing: idle, hopping and spinning, or asleep.
face 'eyes' | 'mouth' | 'none' type's own Eyes alone, eyes with a small mouth that changes with the state, or no face at all.
size number | string 64 Rendered size in px, or any CSS length.
color string type's own Body colour.
ink string auto Face colour. Dark by default, light on a dark body.
brightness number 1 Lightness of the body colour, 0.5 to 1.5.
saturation number 1.5 Saturation of the body colour, 0.5 to 2.5.
shading 'fabric' | 'plastic' | 'crisp' | 'smooth' | 'flat' 'fabric' How the body is lit: plush fur, glossy plastic, a clean lit rim, a soft gradient, or no lighting.
hat 'none' | 'beret' | 'beanie' | 'party' | 'crown' 'none' A hat that sits on the head and turns with it.
glasses 'none' | 'round' | 'square' | 'shades' 'none' Glasses over the eyes.
headphones boolean false Headphones, a cup on either side.
bowTie boolean false A bow tie under the face.
accessoryColor string '#27272b' Colour of the hat, headphones and bow tie.
speed number 1 Multiplier on every animation.
paused boolean false Freezes on the current frame.
seed number per instance 0 to 1. Offsets blink and glance timing. Give two avatars the same seed to move them in step.
interactive boolean true Eyes and head follow a nearby pointer, and a click makes the avatar hop and turn.
turn number 1 How far the head turns from side to side while idle, 0 to 2.
pose { yaw?, pitch?, roll? } – Holds the body at an orientation, in radians, in place of its own motion.
path string – SVG path data in a 100 by 100 box. Replaces the type’s outline.
theme 'auto' | 'dark' | 'light' 'auto' The surface the avatar sits on. auto reads data-theme or a dark/light class on an ancestor, then the system.
ref HTMLCanvasElement | null – The canvas element. Bindable with bind:ref.
...rest HTMLCanvasAttributes – class, style, aria-label, onclick and other attributes are forwarded to the canvas.

Lighting and material

Prop Type Default Description
shadow number 0.35 (1.15 fabric) Strength of the shadow side, 0 to 2.
highlight number 1.3 (1.45 fabric) Strength of the lit side, 0 to 2.
light number 300 (295 fabric) Where the light comes from, in degrees clockwise from the top.
rim number 0.5 (0.6 fabric) The lit rim in crisp, the Fresnel rim in plastic, the back light in fabric. 0 to 2.
spread number 1.55 (1.6 fabric) How far the light wraps round, 0.4 to 2.5.
depth number 0.65 Thickness of the body, 0.2 to 2. Shows when it turns or flips.
roundness number 1 Plastic and fabric: 1 is inflated like a cushion, 0 is a slab with soft edges.
lightFront number 32 Fabric: how far round to the front the key light sits, 0 to 85 degrees.
backLight number auto Fabric: where the back light comes from, in degrees.
backSoftness number 1 Fabric: 0 is a small hard back light, 1 a large soft one.
shine number 0 Fabric: highlights along single fibres, 0 to 2.
sheen number 0 Fabric: a smooth satin sheen over the edge, 0 to 2.
furLength number 1 Length of the pile, 0.3 to 2.5.
furDensity number 1.6 How many fibres, 0.3 to 2.
furFuzz number 0.9 Softness of the silhouette, 0 to 1.
furClumps number 0.4 How much the fibres gather into tufts, 0 to 1.
furCurl number 0.7 How wavy the fibres are, 0 to 1.
furGravity number 0.9 How much the pile hangs down, 0 to 1.

Jump and whirl

Prop Type Default Description
jumpEvery number 8 Seconds between idle jumps, give or take 40%. 0 for none.
jumpHeight number 26 How high, in body units (the body is 100 tall).
jumpTime number 0.68 Seconds in the air.
jumpStretch number 1 Stretch in the air, 0 to 2.
jumpSpin number 1 Whole turns in the air, 0 to 2.
jumpLean number 6 Degrees of lean into a jump.
jumpSquash number 1.15 Squash on the ground, 0 to 2.
jumpSquashTime number 0.37 Seconds the landing squash takes.
jumpSquashEase 'sharp' | 'pulse' | 'soft' | 'bouncy' 'pulse' How the landing squash plays out.
jumpGroundTime number 0.11 Seconds held at the deepest squash.
jumpGroundEase 'sharp' | 'pulse' | 'soft' | 'bouncy' 'pulse' How the weight settles through that hold.
jumpRiseTime number 0.33 Seconds to rise back to shape.
jumpRiseEase 'sharp' | 'pulse' | 'soft' | 'bouncy' 'pulse' How it rises.
jumpClickSquashTime number 0.24 Seconds a click’s jump takes for its landing squash.
jumpLand number 0 When the landing squash begins: seconds before (negative) or after touch-down.
whirl number 0 A ring that trails round a spin. 0 is off, 1 on, up to 2.
whirlSize number 1 Size of the ring, 0.6 to 1.6.
whirlWidth number 1 Thickness of the trail, 0.4 to 2.
whirlLength number 1 Length of the trail, 0.4 to 1.6.
whirlTilt number 1 How open the ring is seen, 0.5 to 1.8.

Notes

  • dot, planet, spark and face="none" are Runeglow additions; the React library does not have them.
  • Fabric and plastic build their material in the background on idle time. An avatar fades in once its material is ready, so a page of them appears together.
  • Each avatar labels itself, for example “Clover bot, working”. Pass aria-label to change the wording.
  • Avatars stop animating while offscreen or in a hidden tab, and show the state’s still pose under prefers-reduced-motion.
  • Every avatar on a page shares one animation loop.