Avatar systems

Every product with users needs an avatar strategy. Three tiers:

1. Real photos — uploaded by the user. Always preferred.
2. Initials — the most common fallback (Slack, GitHub, Linear all use this).
3. Generated avatars — deterministic, fun, branded. DiceBear is the de-facto library.

Pick a strategy before you scale — switching avatar systems mid-product is painful because every user has visually adapted to "what they look like" in your UI.

DiceBear — what it is

DiceBear is an open-source library that generates SVG avatars from a string seed (usually the user's id, email, or name). Same seed always produces the same avatar — so users see the same generated face every visit.

• 30+ style packs (adventurer, bottts, lorelei, pixel-art, etc.).
• HTTP API: https://api.dicebear.com/9.x/<style>/svg?seed=<seed>.
• NPM packages: @dicebear/core + @dicebear/<style> for self-hosting.
• Open source: github.com/dicebear/dicebear and github.com/dicebear/styles.
• License: most styles are CC0 / free; a few designer-contributed styles have specific terms — check per style.

Style catalogue

Quick reference. Preview URLs use seed Felix so you can see what each style looks like. Click the live link to scrub seeds in the playground.

Style	Best for	Live preview
adventurer	Friendly, playful apps
adventurer-neutral	Friendly, no background
avataaars	Cartoon-style, broad appeal
avataaars-neutral	Cartoon, no background
big-ears	Animal-style, casual
big-ears-neutral	Animal, no background
big-smile	Cheerful, simple
bottts	Robots — great for AI agents
bottts-neutral	Robots, no background
croodles	Hand-drawn, scrappy
croodles-neutral	Hand-drawn, no background
dylan	Stylized portraits (paid)
fun-emoji	Emoji-style faces
glass	Frosted glass effect (paid)
icons	Iconographic, abstract
identicon	Geometric, GitHub-style
initials	Letter-based, most common
lorelei	Friendly illustrated portraits
lorelei-neutral	Friendly, no background
micah	Modern minimal portraits
miniavs	Tiny stylized avatars
notionists	Notion-style hand-drawn
notionists-neutral	Notion-style, no background
open-peeps	Vector illustration style
personas	Diverse illustrated portraits
pixel-art	8-bit pixel avatars
pixel-art-neutral	Pixel art, no background
rings	Concentric rings, abstract
shapes	Geometric shapes
thumbs	Thumbprint-style geometric

Browse all styles interactively at dicebear.com/styles. Source repo: github.com/dicebear/styles.

How to choose a style

Implementation

HTTP API (simplest)

<img
  src="https://api.dicebear.com/9.x/lorelei/svg?seed=user-id-here"
  alt="User avatar"
  width="40"
  height="40"
/>

Cache-friendly (the URL is deterministic). For production, proxy through your CDN to avoid hitting DiceBear's API on every request.

NPM (self-hosted)

npm install @dicebear/core @dicebear/lorelei

import { createAvatar } from '@dicebear/core';
import { lorelei } from '@dicebear/lorelei';
 
const avatar = createAvatar(lorelei, { seed: 'user-id-here' });
const svg = avatar.toString();

This avoids the network entirely. Recommended for any serious deployment.

React (with fallback to real photo)

function Avatar({ user, size = 40 }: AvatarProps) {
  if (user.photoUrl) {
    return <img src={user.photoUrl} alt={user.name} width={size} height={size} className="avatar" />;
  }
  
  const seed = user.id ?? user.email;
  return (
    <img
      src={`https://api.dicebear.com/9.x/lorelei/svg?seed=${encodeURIComponent(seed)}`}
      alt={user.name}
      width={size}
      height={size}
      className="avatar"
    />
  );
}

Initials that survive real names

name.split(' ')[0][0] breaks on real data: 🦊 Fox yields half a surrogate pair (�), 👩🏽‍💻 Priya splits into pieces, Christopher Montgomery III becomes CI, a name with leading, trailing or doubled spaces (Sam Lee) finds empty words, and 王秀英 has no spaces at all.

const seg = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
const first = (w: string) => seg.segment(w)[Symbol.iterator]().next().value?.segment ?? '';
const words = name.trim().split(/\s+/).filter((w) => !/^(jr|sr|i{2,3}|iv)\.?$/i.test(w));
const initials = (words.length > 1 ? first(words[0]) + first(words.at(-1)!) : first(words[0] ?? '')).toLocaleUpperCase();

First and last word, by grapheme cluster, uppercased (dana → D). No usable name → the email's first grapheme, then a generic person icon. Give the image an onError that drops to this chain; a 404 must never show the broken-image glyph. flex-shrink: 0 keeps the circle round in a crowded row, and object-fit: cover handles a 4000×200 upload.

Style options & customization

Each DiceBear style accepts options (skin colors, hair styles, background colors, etc.) as URL query params:

https://api.dicebear.com/9.x/lorelei/svg?seed=Felix&backgroundColor=transparent&hair=variant01

See per-style options at dicebear.com/styles. Match the option set to your brand — e.g., restrict hair colors to your palette for tighter visual consistency.

When to apply

• Any product where users need visual identity but real photos aren't reliably available.
• Auto-generated avatars for AI agents or assistants.
• Demo / staging environments where you need realistic-looking user data.
• Public profiles where users haven't uploaded a photo.

When NOT to apply

• Healthcare / regulated industries where avatar variation can feel unprofessional. Use initials.
• High-trust contexts (legal, financial) where the AI-generated look might undermine credibility.
• Products where avatar fidelity is critical (dating apps, hiring). Require real photos.

Gotcha

DiceBear's HTTP API has rate limits. For production, either:

• Self-host via the NPM package (recommended).
• Proxy + cache through your CDN.
• Generate avatars server-side once per user and store as a blob.

Hitting their public API from every page load will eventually rate-limit your users.

Also: a few styles are paid (designer-contributed). Verify license per style at dicebear.com/styles before committing.

Sources

• DiceBear — dicebear.com, github.com/dicebear/dicebear, github.com/dicebear/styles.
• DiceBear style index — dicebear.com/styles.
• Emil Kowalski, skills (MIT, github.com/emilkowalski/skills, a81dbca): skills/break-ui/SKILL.md, skills/break-ui/CATALOG.md (initials from grapheme clusters, the names that break them).
• Related: icon-systems, ai-default-tells, hover-states-subtle, stress-scenarios.