Avatars is a free pixel-art avatar placeholder library with HTTP-API.

Scroll down to see more

How to use

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

HTTP-API

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

https://avatars.dicebear.com/v2/:sprites/:seed.svg

Replace :sprites with male, female or identicon. The value of :seed can be anything you like.

CDN

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

Add the following line to the end of the document body.

<script type="text/javascript" src="https://unpkg.com/@dicebear/avatars@2.0.2/dist/avatars.min.js"></script>

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

<script type="text/javascript" src="https://unpkg.com/@dicebear/avatars-male-sprites@1.0.3/dist/sprites.min.js"></script>

Now you are ready to create your first Avatar.

var avatars = new Avatars(Avatars.sprites.male);
var svg = avatars.create('custom-seed');

NPM

Choose NPM if you want to use Avatars server-side or with webpack.

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.

const Avatars = require('@dicebear/avatars').default;
const SpriteCollection = require('@dicebear/avatars-male-sprites').default;

let avatars = new Avatars(SpriteCollection);
let svg = avatars.create('custom-seed');

Or with ES6-Modules:

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

let avatars = new Avatars(SpriteCollection);
let svg = avatars.create('custom-seed');

Sprite Collections

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

male

@dicebear/avatars-male-sprites

female

@dicebear/avatars-female-sprites

identicon

@dicebear/avatars-identicon-sprites

Your sprite collection here?

You are a designer or developer and would like to contribute with a self-designed sprite collection?
You can start directly with our example sprite collection and create an issue so that we can add your work to the list.

Create issue

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. We believe that everyone should be able to benefit from this library. Also we are always happy about improvements and extensions of contributors, which help us to make DiceBear Avatars even better.