blobatar for developers

Reach for blobatar when an application needs a picture of somebody it has no picture of: a user who has not uploaded an avatar, a commit author, a bot, a team, a repository, a seat in a list. It turns any string into a stable geometric face, so the same handle is the same creature everywhere it appears, with nothing stored anywhere.

Use the HTTP endpoint when the avatar has to be a URL — an <img src>, an email, a Slack or GitHub profile field, an OG image, anything rendered by software you do not control. Use the packages when you are rendering in an app you do own, since generating in-process costs no request and no network. Both produce the same blobatar for the same name.

It is a poor fit for two things. It is not an identicon-compatible drop-in — the shapes are its own, so switching from another generator changes every existing avatar. And it is not an image host: there is no upload, and nothing you send is kept.

One route, no authentication, and every response is safe to hotlink and to cache.

GET https://blobatar.dev/avatar/<name>

A name is anything that stands for somebody — a username, a display name, an email, an id, a Gravatar digest. Names are NFC-normalized, trimmed and lowercased before hashing, so /avatar/Alain and /avatar/alain are one blobatar reached by two URLs; prefer one spelling, because every cache in the path treats them as two. A name containing a slash must be percent-encoded as %2F.

curl -s "https://blobatar.dev/avatar/alain%40example.com?size=64" > blobatar.svg

<img src="https://blobatar.dev/avatar/alain?size=48&background=squircle" alt="" />

$ curl -s -H "Accept: application/json" "https://blobatar.dev/avatar/alain?expresion=happy"
{
  "error": {
    "code": "unknown_parameter",
    "message": "unknown parameter \"expresion\" — expected one of s, size, …",
    "hint": "Remove the parameter or correct its spelling.",
    "status": 400,
    "documentation": "https://blobatar.dev/docs"
  }
}

Zero dependencies, ESM, typed. The core renders a string to SVG markup; the framework packages are thin components over it and pin the core to an exact major, because the two are one release.

bun add blobatar                # the generator, ~4.4 KB gzipped
bun add @blobatar/react         # also /vue, /svelte, /solid, /preact, /react-native
bunx @blobatar/cli alain        # write one to a file

import { Blobatar } from "@blobatar/react";

<Blobatar name={user.email} size={48} />;

There is a shadcn registry too — it installs a wrapper around shadcn's Avatar that falls back to a blobatar when a user has no profile image.

npx shadcn@latest registry add @blobatar=https://blobatar.dev/r/{name}.json
npx shadcn@latest add @blobatar/avatar

The full API — traits, palettes, expressions, animation and what is guaranteed to stay stable across versions — is in the README, and in llms.txt if you are a machine.

Animation is opt-in and off by default. With blobatar/motion.css loaded and an animate prop set, a blobatar breathes, bobs, blinks and glances, all of it seeded from the name so that a grid reads as a crowd rather than a drill team. That layer is pure CSS: the browser runs it and nothing in JavaScript is involved.

One layer is not, and cannot be. A gaze is a function of where the pointer is, which no keyframe can know, so it ships as its own entry point and its own stylesheet — a page that never imports them pays nothing for it.

import { useGaze } from "@blobatar/react/gaze";
import "blobatar/gaze.css";

const { ref, lookAt } = useGaze({ travel: 3, lookAt: "pointer" });
<Blobatar ref={ref} name={user.email} animate="always" size={200} />;

// the option is where it usually looks; the function is where it looks now
lookAt({ x, y });     // a point in client coordinates — a caret, a card
lookAt(el);           // an element: its centre, re-read as the page moves
lookAt("pointer");    // the cursor
lookAt("rest");       // its own centre, held: deliberately not looking
lookAt(null);         // nothing — the idle glance comes back

A separate subpath, so it costs nothing unless you import it — the same bargain @blobatar/react-native/animated makes. Every adapter has one, under the shape its framework reaches an element with: a hook in React and Preact, a composable that takes your template ref in Vue, a ref that is the binding in Solid, an {@attach} in Svelte. Anywhere else, gaze(svgEl) from blobatar/gaze is the same driver without the binding.

travel is the excursion, and it is what opts a blobatar in. --mo-track-travel starts at 0px, so with the stylesheet loaded and the excursion set nowhere every face on the page holds still. It is in viewBox units — the blobatar is 100 across, so 3 is 3% of the face. Without a binding, or for a whole field of them at once, set the property instead: it inherits, and it can be made responsive.

.hero .mo-eyes { --mo-track-travel: 3px; }

The idle glance stands down on its own while the gaze is driving, so the eyes are never being aimed at two things at once. Nothing attaches under prefers-reduced-motion or without a fine pointer, both are watched rather than sampled once, and a settled blobatar under a still pointer schedules no frames at all.

The blobatar at the top of this site is running it, and the password field is a worked example: it watches the caret while you type and looks away when you reveal what you typed.

Three files, at fixed paths, none of which need JavaScript to read:

https://blobatar.dev/openapi.json   the endpoint, as OpenAPI 3.1
https://blobatar.dev/llms.txt        the library, as prose
https://blobatar.dev/sitemap.xml     every page here

The spec is generated from the endpoint's own parser, so its enums are the values the endpoint actually accepts rather than a list somebody remembered to update. Every operation carries a unique operationId and a description, which is what function-calling formats read.

The endpoint is a single Cloudflare Worker with no bindings, no storage and nothing account-specific in its configuration, kept that way precisely so a fork deploys unchanged. Clone apps/api, deploy, and it answers on your own hostname — including its own /openapi.json, which names your origin rather than this one.

It is MIT, and so is everything else here. Questions and bugs go to contact.