Documentation
Avatarsverse is a free, open-source library of avatar images served over a global CDN.
Overview
Every avatar has a permanent, stable URL on jsDelivr. You can drop any URL into an <img> tag and it will work instantly — no backend, no signup, no rate limits.
The NPM package adds a deterministic mapping from any string to an avatar URL. Pass the same seed (email, username, user ID) and you will always get the same avatar back, across devices and deployments.
Currently one style is available: voxel. More styles are in the works — follow the GitHub repo to get notified.
Installation
To use avatar URLs directly, there is nothing to install. Copy a URL from the homepage and use it as-is. For the deterministic helper in a JS/TS project, install the package with your preferred package manager: npm install avatarsverse.
Usage
Import avatarUrl and pass any string as the seed. The function hashes the seed and returns a CDN URL. A common pattern is to fall back to a deterministic avatar when a user hasn't uploaded a photo yet — use user.avatarUrl ?? avatarUrl(user.id).
import { avatarUrl } from "avatarsverse";
const url = avatarUrl("alice@example.com");
// → always the same avatar for this seed
<img src={url} alt="Alice" width={64} height={64} />API reference
avatarUrl(seed, category?, total?, tag?)
Returns a jsDelivr CDN URL for the avatar deterministically selected by the given seed.
| Parameter | Type | Default | Description |
|---|---|---|---|
| seed | string | required | Any string used to deterministically pick an avatar |
| category | string | "voxel" | Avatar style to draw from |
| total | number | undefined | Legacy — limits pool size; omit in new projects |
| tag | string | "main" | jsDelivr release tag — pin to a version to freeze avatar assignments |
Returns string — a fully-qualified CDN URL.
FAQ
Why am I getting a different avatar on another device?
The seed must be exactly the same. Pick one stable identifier per user (e.g. a user ID) and use it consistently.
Will avatars change if I update the package?
They can. The avatar selected for a seed is determined by the manifest bundled inside the package. If a new version adds avatars to the pack, the mapping shifts. To freeze assignments, pin both your package version in package.json and pass the matching release tag as the fourth argument so the CDN URL stays consistent too:
avatarUrl("alice@example.com", "voxel", undefined, "0.1.0")Is there a rate limit or cost?
No. Avatarsverse is released under the MIT license — free for personal and commercial use. Images are served via jsDelivr, a free public CDN with no rate limits for reasonable use.
Can I self-host?
Yes. Clone the GitHub repo and serve the avatars/ folder from your own CDN. Update the CDN_BASE constant in index.ts to point to your URL.
Will more avatar styles be added?
Yes, more packs are planned. Watch the GitHub repo for releases.