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 gray silhouette, DiceBear generates a unique, deterministic SVG avatar from any seed, so every user gets a distinct picture 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, which works well 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.

35+ 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/10.x/initials/svg?seed=JD

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

<img
  src="https://api.dicebear.com/10.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/10.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/10.x/thumbs/svg?seed=${encodeURIComponent(userId)}`;

https://api.dicebear.com/10.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 { Avatar } from '@dicebear/core';
import thumbs from '@dicebear/styles/thumbs.json' with { type: 'json' };

function getPlaceholderAvatar(userId) {
  return new Avatar(thumbs, {
    seed: userId,
    size: 48,
    borderRadius: 50,
  }).toString();
}

With the PHP library

Use the PHP library for server-side rendering without an additional HTTP request. For full installation and API details, see the PHP library documentation.

<?php

use Composer\InstalledVersions;
use DiceBear\Style;
use DiceBear\Avatar;

$basePath = InstalledVersions::getInstallPath('dicebear/styles');
$definition = json_decode(file_get_contents($basePath . '/src/thumbs.json'), true);

$style = new Style($definition);

function getPlaceholderAvatar(Style $style, string $userId): string {
  return (string) new Avatar($style, [
    'seed' => $userId,
    'size' => 48,
    'borderRadius' => 50,
  ]);
}

With the Python library

Use the Python library for server-side rendering without an additional HTTP request. For full installation and API details, see the Python library documentation.

import json
from importlib.resources import files

from dicebear import Avatar, Style

definition = json.loads(
    files("dicebear_styles").joinpath("thumbs.json").read_text("utf-8")
)

style = Style(definition)

def get_placeholder_avatar(user_id: str) -> str:
    return Avatar(style, {
        "seed": user_id,
        "size": 48,
        "borderRadius": 50,
    }).to_string()

With the Rust library

Use the Rust library for server-side rendering without an additional HTTP request. For full installation and API details, see the Rust library documentation.

use dicebear_core::{Avatar, Error, Style};
use serde_json::json;

let style = Style::from_str(dicebear_styles::THUMBS)?;

fn placeholder_avatar(style: &Style, user_id: &str) -> Result<String, Error> {
    let avatar = Avatar::new(style, json!({
        "seed": user_id,
        "size": 48,
        "borderRadius": 50,
    }))?;

    Ok(avatar.to_string())
}

With the Go library

Use the Go library for server-side rendering without an additional HTTP request. For full installation and API details, see the Go library documentation.

import (
	dicebear "github.com/dicebear/dicebear-go/v10"
	"github.com/dicebear/styles/v10"
)

style, _ := dicebear.NewStyle([]byte(styles.Thumbs))

func placeholderAvatar(style *dicebear.Style, userID string) (string, error) {
	avatar, err := dicebear.NewAvatar(style, map[string]any{
		"seed":         userID,
		"size":         48,
		"borderRadius": 50,
	})
	if err != nil {
		return "", err
	}

	return avatar.SVG(), nil
}

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 35+ avatar styles

Tip: always define a size

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

// JS library
new Avatar(thumbs, { seed: userId, size: 48, borderRadius: 50 });

// PHP library
new Avatar($style, ['seed' => $userId, 'size' => 48, 'borderRadius' => 50]);

# Python library
Avatar(style, {"seed": user_id, "size": 48, "borderRadius": 50})

// Rust library
Avatar::new(&style, json!({ "seed": user_id, "size": 48, "borderRadius": 50 }))?;

// Go library
dicebear.NewAvatar(style, map[string]any{"seed": userID, "size": 48, "borderRadius": 50})

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