npface

English

What is it?

npface renders a small helmet-shaped face — a deep-navy rounded square helmet, white visor slot, two neon-green rounded-square eyes (the npcrew brand mark, flat 2D) — and makes it emote. Expressions come entirely from the two eyes, the visor and tiny helmet motions: blinks, squint-smiles, wide eyes, side glances, sleepy half-lids, reading saccades, a radar-like "searching" circle, dizzy X-eyes, z z z, nods, head tilts, breathing.

Give it a semantic state name and it takes care of the rest:

face.set('thinking'); // → idle → thinking → search-docs → search-web → working → proud …

• 13 states: sleep · wake · idle · blink · happy · proud (complete) · thinking · search-docs · search-web · working · waiting · error (dizzy) · sad (tired) — plus aliases (searching, rag, browsing, tired …; searchDocs / search_docs are normalised too), unknown names fall back to idle, and you can register your own.
• Zero dependencies, framework-agnostic core (plain SVG/DOM, built-in springs & easing, one shared requestAnimationFrame loop). ~9 KB gzip.
• React bindings (npface-react): <Npface state="working" />. Vue can follow.
• Alive by default: breathing, random glances, auto-blink, per-state rhythm; optional eyes-follow-pointer.
• Considerate: pauses off-screen (IntersectionObserver), honours prefers-reduced-motion (static poses + minimal transitions), role="img" + aria-label.
• Themeable: helmet / visor / eye colours, light & dark palettes, any size.
• Pure data states: every expression is a data file (eye shapes + head pose + rhythm) separate from the renderer.

Install

npm i npface            # core — vanilla / any framework
npm i npface-react      # React bindings (depends on npface)

CDN / no build step:

<script src="https://unpkg.com/npface/dist/npface.min.js"></script>
<script>
  const face = npface.createNpface('#avatar', { state: 'idle', size: 64 });
</script>

Quick start

Vanilla

import { createNpface } from 'npface';

const face = createNpface(document.querySelector('#avatar')!, {
  state: 'idle', // initial state (alias: emotion)
  size: 48, // px, or any CSS length string
  colors: { body: '#0f1d3a', visor: '#fff', eye: '#c7f636' },
  follow: true, // eyes follow the pointer (alias: gaze)
});

face.set('thinking'); // switch with a spring transition
face.pulse('proud'); // play once, then fall back to the previous state
face.pulse('blink'); // a single blink
face.look(0.6, -0.3); // look in a direction (-1..1); face.look(null) releases
face.follow(false);
face.destroy();

React

import { useRef } from 'react';
import { Npface, type NpfaceHandle } from 'npface-react';

export function Employee({ status }: { status: string }) {
  const face = useRef<NpfaceHandle>(null);
  return (
    <button onClick={() => face.current?.pulse('happy')}>
      <Npface ref={face} state={status} size={48} follow />
    </button>
  );
}

npface-react is marked "use client" and works with Next.js App Router. Props map 1:1 to the options below; changing state triggers a transition. The imperative handle (pulse, blink, look, follow, setColors, …) is the core instance.

API

createNpface(target, options?) → Npface

target is an element or CSS selector; the <svg> is appended to it.

Instance

Also exported: STATES, STATE_NAMES, ALIASES, registerState(name, def), resolveStateName(), BASE_EYE, BASE_HEAD, SPRINGS, PALETTE, LIGHT_COLORS, DARK_COLORS, and the geometry helpers (HELMET_PATH, eyePath, …) for static rendering.

States