quick-avatar

Quick-avatar is a small TypeScript library that generates profile picture images for software projects without requiring any network request, external API, or server. You give it a seed — any text string such as a user's email address or username — and it always returns the same hand-crafted PNG illustration for that seed. This makes it "deterministic": the same input always produces the same avatar, so user profiles stay visually consistent across sessions.

The library works by mapping the seed string to one of 64 pre-drawn PNG illustrations from a built-in collection called Doteye. Three visual variants are available: solid white background, transparent background, and a black-and-white transparent version. Because the images are already bundled with the package, no external service is needed.

You would use this when building a web application, mobile backend, or any tool where users need a default profile picture but you do not want to rely on third-party avatar APIs or generate images on the fly. The library is installable via npm and works in browsers, in React applications, and in server-side Node.js environments. In browser mode it loads only the single image it needs, keeping download size small. In CDN mode it produces a direct URL pointing to the image file so nothing is bundled at all.

Developers can also add custom illustration sets by placing PNG files in a folder and running a provided script that converts them into the required format.