@happypizzastudio/pixels

Fully generative mirrored pixel avatars based on a seed.

Every avatar is mirrored down the middle, so it reads as a face. Same seed, same face, every time — deterministic across server and client, zero dependencies, SVG out.

Live playground → happypizza.studio/pixels

npm i @happypizzastudio/pixels

Quickstart

import { generatePixelAvatar } from '@happypizzastudio/pixels'

const avatar = generatePixelAvatar('[email protected]')

avatar.svg    // '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10" ...>'
avatar.hash   // '4b53f0e' — short stable id for the seed
avatar.colors // ['hsl(148, 90%, 60%)', ...] — the seeded 3-color palette

Drop it in an <img> with the data-URI helper:

import { generatePixelAvatar, toDataUri } from '@happypizzastudio/pixels'

img.src = toDataUri(generatePixelAvatar(user.id))

React

import { generatePixelAvatar } from '@happypizzastudio/pixels'

function Avatar({ seed, size = 48 }: { seed: string; size?: number }) {
  const { svg } = generatePixelAvatar(seed)
  return (
    <div
      style={{ width: size, height: size }}
      dangerouslySetInnerHTML={{ __html: svg }}
    />
  )
}

Works the same in server components — the generator is pure and environment-free, so SSR output always matches the client.

Options

generatePixelAvatar(seed, {
  grid: 10,                  // pixel resolution, 4–24 (default 10)
  background: 'transparent', // fill behind the pixels (default transparent)
  hue: 225,                  // lock the palette to a hue family, 0–359
})

Color locking

By default the palette is derived from the seed. Pass hue to lock every avatar to a color family — brand color, team color, whatever:

generatePixelAvatar('pepperoni', { hue: 225 }) // the blue one
generatePixelAvatar('pepperoni', { hue: 330 }) // the pink one

Locking a hue never changes the pixel pattern — the shape belongs to the seed, the color is an independent axis. Same seed, same silhouette, any color.

How many avatars are there?

Seeds are hashed through a 64-bit funnel (two independent 32-bit string hashes feeding a 128-bit-state PRNG), so the generator can reach ~1.8 × 10¹⁹ distinct faces — and with the auto palette plus 360 lockable hues, over 6.6 × 10²¹ distinct avatars at the default grid size. You'd need to mint roughly 5 billion before two random seeds have a coin-flip chance of colliding.

API

| Export | Description | | --- | --- | | generatePixelAvatar(seed, options?) | Returns { seed, hash, grid, cells, colors, svg } | | toDataUri(avatar \| svg) | Encodes the SVG as a data: URI for <img src> / CSS url() | | randomSeed() | Random human-friendly seed, e.g. 'cobalt-x7f2' | | PixelAvatar, PixelOptions | TypeScript types |

cells is the raw row-major grid (0 = empty, 1..3 = palette index + 1) if you want to render to canvas, a terminal, a Lego wall — anything that isn't SVG.

License

MIT © Happy Pizza Studio