robot-heads README

The project's README from github.com/fayazara/robot-heads. As one markdown file: README.md.

robot-heads

Animated 3D robot heads for React. Glossy, TV-headed bots with an LED-matrix face that shows what your agent is doing — thinking, searching, listening, speaking and more — in four shapes, with a springy antenna, knob ears and a light on top that changes with the state.

Drawn on a 2D canvas: no WebGL, no runtime dependencies.

Playground →

Install

npm install robot-heads

React 18 or newer is a peer dependency.

Quick start

import { RobotHead } from 'robot-heads';

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

Shapes

One head, four outlines. Every shape carries the same screen, ears, antenna, screws and back panel, and moves the same way.

<RobotHead shape="rectangle" />  {/* the classic TV (default) */}
<RobotHead shape="square" />
<RobotHead shape="circle" />     {/* a porthole */}
<RobotHead shape="hexagon" />    {/* a nut, flat on top */}

The list is exported as robotHeadShapes.

States

Each state has its own face on the screen, its own motion and its own antenna light. Switching states plays a short glitch and cross-fade, and the head eases into its new pose.

State Screen Motion
idle block eyes that blink and glance looks around, hops now and then
thinking heavy-lidded eyes looking up, three pulsing dots head tilted up, switching sides; amber light pulses
searching darting eyes, a beam sweeping the whole screen head sweeps side to side; cyan beacon
listening alert eyes over a live equaliser head cocked, small nods; steady green light
speaking a mouth that moves with the words bobs as it talks
working focused eyes looking down, a progress bar busy bobbing, a hop with a spin now and then
happy ^ ^ eyes and a smile bouncy hops
error red X X eyes shakes its head; red light blinks
sleeping closed eyes and rising z's head drooped, slow breathing; light off

The list is exported as robotHeadStates.

Props

<RobotHead
  shape="rectangle"       // rectangle, square, circle or hexagon
  state="idle"            // what it is doing (above)
  size={160}              // px, the box the robot rests in (below)
  color="#2b49a3"         // the shell
  trimColor="#93a6c8"     // the ears and the antenna's collar
  screenColor="#e8f2ff"   // the LEDs
  speed={1}               // multiplier on every animation
  paused={false}          // hold the state's still pose
  interactive             // follow the pointer, hop and spin on a click
  antenna                 // the antenna's stem and light; off, the knob stays
  floorShadow             // the soft shadow under the head
  seed={0.3}              // 0–1, desyncs blinks and glances in a row of heads
/>

Any other attribute (className, style, onClick, aria-label, …) goes on the element, and a ref reaches the <canvas> inside it.

Sizing and layout

size is the robot itself: the element is a size × size box with the robot at rest centred in it, filling it, antenna included. It lines up with text, sits in a flex row, and centres like an icon or an avatar would.

Its motion is not part of that box. Hops, the antenna's glow and the floor's shadow draw past its edges — like a CSS box-shadow, they overflow without taking any room in your layout, and only the box takes clicks. So margins, flex and grid treat it as exactly size × size; the one thing to watch is a parent with overflow: hidden right round it, which would cut off a hop.

Behaviour

How it is drawn

The head is real geometry: a shell with a rolled edge — its outline a convex polygon of corner centres grown by a corner radius, so one builder makes every shape — lathed knob ears and an antenna collar, built once as quad meshes. Each frame it is turned with the pose and projected, back faces are culled, and every quad is lit by a small studio model: a key light, a fill, a sky dome, a softbox and the key's window caught as clear-coat reflections with Fresnel, a cool back light rimming the silhouette, and a filmic tone curve.

The flat front and back are plates drawn in their own plane with baked relief: the lip rolling into the screen hole, the rubber gasket, the shadow the lip casts onto the glass, screws, and vents on the back. The glass sits a little behind the bezel, so it slides against it as the head turns. The LED matrix covers the whole screen, the face centred on it; the LEDs are drawn crisp, then bloomed from a one-pixel-per-LED image scaled up smooth. The antenna is a damped spring that whips when the head hops, lands or tilts, topped with a frosted bulb lit from inside.

Development

The repo is a pnpm workspace: the library at the root, the playground in site/ — a React app on Vite served by a Cloudflare Worker. The playground runs on the library's source, so edits hot-reload there.

pnpm install
pnpm run dev       # the playground
pnpm run build     # the library, to dist/
pnpm run typecheck
pnpm run deploy    # build and deploy the playground Worker

src/            the library
  RobotHead.tsx   the component
  tv/             the TV head: geometry, lighting, faces, motion, renderer
site/           the playground (Vite + Cloudflare Worker)

License

MIT © Fayaz Ahmed

The playground is set in Open Runde by Laurids Kern, under the SIL Open Font License 1.1 (site/public/fonts/OFL.txt). The font is not part of the npm package.

robot-heads (fayazara/robot-heads)

Searching Database…

358 ·GitHub
Robot-heads
What is this?robot-heads is a React component library that renders animated, TV-headed robot avatars with LED-matrix faces showing what an AI agent is currently doing — thinking, searching, listening, speaking and more.
Is this a 3D library or something lighter?It only looks 3D: everything is drawn with real geometry projected onto a flat HTML5 2D canvas, so there's no WebGL and no runtime dependencies to pull in.
How do I add it to a React project?Install the package from npm and drop the component into your app, picking a shape and a state prop; there's a Quick start section in the README and a hosted playground to try it first.
Do I need a specific React version?Yes — React 18 or newer is required as a peer dependency, otherwise the component ships with no other runtime dependencies.
Any layout gotchas I should know about?The box itself is a tidy size × size square for layout purposes, but hops, the antenna glow and the floor shadow draw outside that box like a CSS box-shadow — so a parent with overflow: hidden can clip a hop.
What states can a robot head display?Nine built-in states are included — idle, thinking, searching, listening, speaking, working, happy, error and sleeping — each with its own face, motion and antenna light, exported as robotHeadStates.
Is it safe to put many robot heads on one page?Yes — every head shares a single animation loop that sleeps when the tab is hidden, and heads of the same shape and size share baked textures to keep rendering cheap.
Does it respect reduced-motion settings?Yes — with prefers-reduced-motion: reduce or a paused prop, it draws the still pose for the current state instead of animating.
Is the whole package MIT licensed?The library code is MIT licensed, but the playground's Open Runde font is separately licensed under the SIL Open Font License and is not bundled into the npm package.
What are similar projects?Libraries.dev, arc-library, react-icons, loadersz-core, shaders, chakra-ui, base-ui, canvas-ui
Which topics is it in?robot, react-components, npm-package, canvas, accessibility, component-library, ui-components, animation, ui, react, free, npm
Creator
fayazara
Size
0.9 MB
Stars
358
Updated
CommitOct 10
Age
8d
Commits · 90 Days