fayazara/robot-heads

robot-heads – Animated 3D robot heads for React

What it is

• An npm package that provides a <RobotHead> React component. The component draws a stylised robot head on a 2‑D canvas (no WebGL) and animates it to reflect an agent’s state (idle, thinking, listening, etc.).

Key features

• Four geometric shapes – rectangle, square, circle, hexagon – all share the same screen, antenna, ears and motion.
• State‑driven faces – each state (idle, thinking, searching, listening, speaking, working, happy, error, sleeping) has its own LED‑matrix face, motion pattern and antenna light colour.
• Customisable appearance – colour props for shell, trim, screen; size in pixels; animation speed; optional antenna, floor shadow, and a seed to desynchronise multiple heads.
• Interactivity – with interactive (default) the head follows the mouse pointer and hops/spins on click; respects prefers-reduced‑motion and a paused prop.
• Performance‑friendly – all heads share a single animation loop, which pauses when the tab is hidden; heads of identical shape/size reuse baked textures.
• Accessible – canvas gets role="img" and an aria-label describing the current state.

How it works

• The head geometry is generated as a convex polygon with rounded corners, then lathed into 3‑D‑like meshes (ears, antenna collar). Each frame the mesh is transformed, back‑faces culled, and lit by a simple studio lighting setup (key, fill, rim, sky dome) with a filmic tone curve.
• The front screen is an LED matrix; the face is rendered crisp and then bloomed for a glow effect.
• All drawing is done on a regular HTML <canvas> element, avoiding heavy WebGL dependencies.

Typical usage

import { RobotHead } from 'robot-heads';

function Agent({status}: {status: 'idle' | 'thinking' | 'speaking'}) {
  return <RobotHead state={status} size={160} />;
}

You can change the shape, colours, speed, and enable/disable the antenna, shadow, or interactivity via props.

Development & playground

• The repo is a pnpm workspace with the library at src/ and an interactive playground under site/ (Vite + Cloudflare Worker). Running pnpm run dev launches the playground, which hot‑reloads changes to the library.
• Build with pnpm run build to produce the distributable files in dist/.

License

• MIT‑licensed, authored by Fayaz Ahmed.

Who might use it

• Front‑end developers building AI chat‑bots, voice assistants, or any interactive agent UI who want a lightweight, animated visual cue for the agent’s current activity.

---

All details are taken directly from the repository’s README.