Using DiceBear as an Avatar Placeholder API

An avatar placeholder replaces the generic default shown when a user hasn't uploaded a profile picture yet. Instead of a grey silhouette, DiceBear generates a unique, deterministic SVG avatar from any seed — making every user feel represented from the moment they sign up.

Why DiceBear as a Placeholder?

Deterministic

The same seed always produces the same avatar. Use a user ID or email as the seed and the placeholder stays consistent across sessions and devices.

Zero Upload Required

No images to store, no moderation needed. The avatar is generated on the fly — perfect for new users without a profile picture yet.

Self-Hostable

Run your own instance of the HTTP API for full control over availability and data retention.

30+ Styles

Pick the visual style that fits your product — from abstract geometric shapes to illustrated characters.

With the HTTP API

The simplest approach: use a DiceBear API URL as the src of an <img> tag. Use a stable identifier as the seed — a numeric user ID works well. For full options and rate limit details, see the HTTP API documentation.

https://api.dicebear.com/9.x/initials/svg?seed=JD

https://api.dicebear.com/9.x/pixel-art/svg?seed=user-42

<img
  src="https://api.dicebear.com/9.x/initials/svg?seed=JD"
  alt="User avatar"
  width="48"
  height="48"
/>

Fallback on Image Error

Combine DiceBear with an onerror handler to fall back gracefully when a user's uploaded photo fails to load:

<img
  src="/uploads/user-123.jpg"
  onerror="this.src='https://api.dicebear.com/9.x/pixel-art/svg?seed=123'; this.onerror=null;"
  alt="User avatar"
/>

Using a User ID as Seed

Pass a stable, unique identifier as the seed to ensure each user always gets the same placeholder:

const userId = 'user-8f3a2c';
const avatarUrl = `https://api.dicebear.com/9.x/thumbs/svg?seed=${encodeURIComponent(userId)}`;

https://api.dicebear.com/9.x/thumbs/svg?seed=user-8f3a2c

With the JavaScript Library

Use the JS library for server-side rendering or to embed the SVG directly in your markup without an additional HTTP request. For full installation and API details, see the JavaScript library documentation.

import { createAvatar } from '@dicebear/core';
import { thumbs } from '@dicebear/collection';

function getPlaceholderAvatar(userId) {
  return createAvatar(thumbs, {
    seed: userId,
    size: 48,
    radius: 50,
  }).toString();
}

Choosing a Style

Different styles suit different use cases. Click a style to see all available options.

Initials Apps where showing user initials is conventional

Identicon Developer tools, version control, technical platforms

Pixel Art Gaming, retro, or developer-focused communities

Thumbs Friendly consumer apps and social platforms

Shapes Abstract, neutral placeholder for any context

Browse all 30+ avatar styles

Tip: Always Define a Size

Specify a size or CSS dimensions to avoid layout shift while the avatar loads:

// JS library
createAvatar(thumbs, { seed: userId, size: 48, radius: 50 });

// HTTP API
https://api.dicebear.com/9.x/thumbs/svg?seed=user-123&size=48&radius=50