React component

@outpacelabs/avatars

A deterministic mesh-gradient avatar for any seed, rendered on a <canvas> — the same seed always yields the same gradient, with no stored images and no network. Self-contained: the gradient engine is bundled in.

Terminal

npm i @outpacelabs/avatars

npm ↗GitHub ↗CC BY 4.0

Get started

Installation

Install with your package manager of choice. React 18 or newer is the only peer dependency.

npm i @outpacelabs/avatars
pnpm add @outpacelabs/avatars
yarn add @outpacelabs/avatars
bun add @outpacelabs/avatars

Basics

Usage

Import the component and give it a seed. That's it — the same seed always renders the same gradient, so a user id or email is a stable avatar with nothing to store.

avatar.tsx

import { GradientAvatar } from "@outpacelabs/avatars";

export function Avatar({ user }) {
  return <GradientAvatar seed={user.id} size={96} />;
}

jane@example.com

same seed → same gradient

API

Props

PropTypeDefaultDescription

seedstring | number—Any value; each unique seed is a unique gradient.

sizenumber32Rendered size in pixels.

radiusnumber | string"9999px"Corner radius. Number = pixels, string = any CSS length. Pass 0 for a square.

classNamestring—Extra classes on the wrapper <span>.

styleCSSProperties—Extra inline styles merged onto the wrapper.

Recipes

Sizes & shapes

size scales the avatar; radius reshapes it. It defaults to a full circle — pass a number for a rounded square or 0 for a hard square.

circle

radius={18}

radius={0}

<GradientAvatar seed="studio" size={84} />            // circle
<GradientAvatar seed="studio" size={84} radius={18} /> // rounded square
<GradientAvatar seed="studio" size={84} radius={0} />  // square

Advanced

Engine helpers

The bundled engine is re-exported so you can render gradients outside React — to a data URL for an <img>, a Blob for the clipboard, or a full-resolution download.

drawMeshGradient(ctx, seed, size)Paint the raw mesh into a 2D canvas context. The lowest-level primitive.

renderGradient(canvas, seed, options?)Render a seed into a canvas with the signature soft blur baked in.

gradientToDataURL(seed, options?) → stringRender and return a data URL. Handy for <img src>, downloads, or copy.

gradientToBlob(seed, options?) → Promise<Blob | null>Render and resolve a Blob — e.g. to write to the clipboard.

generatePalette(seed) → GradientPaletteThe colors and harmony rule behind a seed, without painting anything.

seedFromString(input) → number / toSeed(seed) → numberThe deterministic hashing used to turn any value into a numeric seed.

export.ts

import { gradientToDataURL, generatePalette } from "@outpacelabs/avatars";

// A 512×512 PNG data URL, no React required.
const src = gradientToDataURL("jane@example.com", { size: 512 });

// Just the colors behind a seed.
const { colors, harmony } = generatePalette("jane@example.com");

Types are exported too: GradientPalette, Harmony, RenderOptions, and ExportOptions.

Legal

License

Free to use under CC BY 4.0 — use it anywhere, just keep the attribution to Outpace Studios.