Avatars is an avatar placeholder library for designers and developers. You can choose between simple identicons and lovely designed characters.

And best of all: We provide a simple and free HTTP API that you can use right away!

Don't use sensitive or personal data as seed!
See README.md for advanced options
Create your ownarrow

How to use

You can start directly with our free HTTP-API or alternatively use the JavaScript library.


Our free HTTP-API is the easiest way to use Avatars. Just use the following URL as image source.


Replace :sprites with male, female, human, identicon, initials, bottts, avataaars, jdenticon, gridy or code. The value of :seed can be anything you like - but don't use any sensitive or personal data here!

The used sprite collection may offer additional options, which can be set using GET parameters. For example, to create a happy male avatar with the seed john, the following URL can be used:



Choose NPM if you want to use a spriteCollection that is not available via the HTTP-API.

Install the Avatars package with the following command.

$ npm install --save @dicebear/avatars

You also need to add a sprite collection. In our example, we will use the male sprite collection.

$ npm install --save @dicebear/avatars-male-sprites

Now you are ready to create your first Avatar.

import Avatars from '@dicebear/avatars';
import sprites from '@dicebear/avatars-male-sprites';

let options = {};
let avatars = new Avatars(sprites, options);
let svg = avatars.create('custom-seed');

Available options

The following options are available for each sprite collection.

radiusrnumber0Avatar border radius
base64boolfalseReturn avatar as base64 data uri instead of XML
Not supported by the HTTP API
widthwnumbernullFixed width
heighthnumbernullFixed height
marginmnumber0Avatar margin in percent
HTTP-API limitation Max value 25
backgroundbstringnullAny valid color identifier
HTTP-API limitation Only hex (3-digit, 6-digit and 8-digit) values are allowed. Use url encoded hash: %23.
userAgentstringwindow.navigator.userAgentUser-Agent for legacy browser fallback
Automatically detected by the HTTP API

More available options can be found in the README.md of each sprite collection.

Sprite Collections

Do you want to create male, female or abstract avatars?
You have the choice between several lovely designed sprite collections.































Your sprite collection here?

You are a designer or developer and would like to contribute with a self-designed sprite collection?

Create an issue so that we can add your work to the list.

Frequently Asked Questions

What is this library best suited for?

DiceBear Avatars is best suited for designers and developers to create avatar placeholders. But you are free to use the generated avatars for other purposes.

Does a seed always return the same avatar?

Yes, as long as the same version of a sprite collection is used, a seed will always return the same avatar. This allows you to represent user identities with DiceBear Avatars, for example.

Will the library remain free of charge?

DiceBear Avatars is developed open source and will remain free of charge. I believe that everyone should be able to benefit from this library. Also I'm always happy about improvements and extensions of contributors, which help me to make DiceBear Avatars even better.

Can I use an email address or other sensitive or personal information as a seed?

No! Sensitive or personal data should never be used as seed. The seed could be read from the source code. The generated avatar could also reveal the seed.

How stable is the HTTP API?

DiceBear Avatars is a hobby project. Therefore, I can not guarantee the availability of the HTTP API. Access to the HTTP-API can be temporarily or permanently blocked. I also reserve the right to completely discontinue the HTTP API.

Documentation realized with GatsbyJS, react, bootstrap and octicons.
"QR Code" is a registered trademark of DENSO WAVE INCORPORATED.