page-mascot is an open-source (MIT) React component that adds an interactive character to a website. The mascot watches the cursor and turns its head to follow it, and blinks or reacts when you click on it. It ships with 52 premade characters, or you can have an AI agent draw a custom one.

How do I install page-mascot?

Install it with `npm i page-mascot`, then import the Mascot component and point it at two sprite sheets (a directions sheet and a reactions sheet). Pick a character from the demo page, download its two sheets into your public folder, and pass the paths as props.

Can I make a custom mascot that looks like me?

Yes. Install the page-mascot agent skill with `npx skills add nilbuild/page-mascot --skill page-mascot --global --yes`, then ask your agent something like '/page-mascot make one that looks like me' with a photo attached. It draws the nine directions and nine expressions, builds them into aligned sheets, and drops the component on your page. Drawing requires an image tool (Codex's built-in, or the OpenAI Images API via an OPENAI_API_KEY).

How does the cursor-following work technically?

Each character is two 3x3 sprite sheets — nine head directions and nine expressions. The pointer's angle relative to the mascot picks a cell on the directions sheet (with a dead zone so the head settles when the cursor is near), and a click briefly shows a cell from the reactions sheet.

Is page-mascot accessible and performance-friendly?

Yes. Cursor tracking switches off when there's no fine pointer (e.g., touch devices), the click squash animation honors prefers-reduced-motion, and the component takes a screen-reader label prop. It's a lightweight sprite-sheet approach rather than heavy animation.

page-mascot: Add Cursor-Following Character Mascots to Your Website

By Prahlad Menon Published 2026-09-15 3 min read

Every so often a project shows up that’s pure delight rather than pure utility — and page-mascot is one of those. It puts a little cursor-following character on your website: it watches your pointer, turns its head to follow it, and blinks or reacts when you poke it.

It’s MIT-licensed, sitting at ~440 GitHub stars, and made by Kamran Ahmed (of roadmap.sh fame).

What It Does

The mascot is a single React component that adds a whole layer of personality to a UI:

Follows the cursor — the character’s head tracks your pointer’s angle in real time
Reacts to clicks — poke it and it blinks or pulls an expression for half a second
52 premade characters — pick one off the demo page and drop it in
Custom characters — have an AI agent draw a brand-new one, even one based on your photo

The Simplest Possible Setup

Install and point the component at two sprite sheets:

npm i page-mascot

import { Mascot } from 'page-mascot'

<Mascot
  directions="/mascots/fox-directions.webp"
  reactions="/mascots/fox-reactions.webp"
/>

Pick a character on the demo page, download its two sheets into your public/mascots folder, and you’re done. That’s the entire integration.

Let an AI Agent Draw You One

This is the part that makes it feel very 2026. Install the skill:

npx skills add nilbuild/page-mascot --skill page-mascot --global --yes

Then just ask your agent in natural language:

/page-mascot a chibi otter with chocolate-brown fur
/page-mascot make one that looks like me        [attach a photo]
/page-mascot a chibi fox, in the riso style

The agent draws the nine directions and nine expressions, builds them into two aligned sprite sheets, verifies the character doesn’t visually jump between frames, and wires the component onto your page. Drawing needs an image tool — Codex has its own, while Claude Code goes through the OpenAI Images API (export OPENAI_API_KEY=sk-...). You can also grab the raw prompts and use them in any chat UI.

How It Works Under the Hood

The engineering is refreshingly simple. Each character is two 3×3 sprite sheets: nine head directions and nine expressions.

The pointer’s angle relative to the mascot picks a cell on the directions sheet
A dead zone keeps the head settled when the cursor is close, so it doesn’t jitter
A click flashes a cell from the reactions sheet for half a second

Because only the sprite lookup changes, the same character can be rendered in six styles — colour, ink, sketch, riso, paper, and pixel — while the alignment holds.

Thoughtful Defaults

It’s not just a toy; the details show care:

Cursor tracking switches off when there’s no fine pointer (touch devices don’t get a confused, frozen mascot)
The click squash honors prefers-reduced-motion
A label prop tells screen readers what the character is
Configurable size and className props keep it easy to style

Why It’s Worth a Look

Personality in web UI has been trending back — think of the little characters on landing pages that make a site feel alive rather than corporate. page-mascot gives you that in a few lines of React, with an escape hatch to generate a fully custom, on-brand (or on-your-face) character via an AI agent.

It’s the kind of small, joyful primitive that’s easy to add and surprisingly memorable for visitors.

Repo: github.com/nilbuild/page-mascot · Demo: koboyo.com/page-mascot