JS-Library

The library is written in TypeScript / JavaScript and can be used in the browser and also in Node.js. In other environments you may be interested in the HTTP API or the CLI.

The library is a pure ESM package. Sindre Sorhus has written a great help page if you are new to ESM packages.

Installation

At least two packages are needed. The first package is the core library @dicebear/core and the second package is an avatar style. In our examples we use the package @dicebear/collection which contains all official avatar styles.

npm install @dicebear/core @dicebear/collection

TIP

We highly recommend the use of a bundler with tree shaking functionality. If you don't have one, take a look at our guide "Using the library without tree shaking".

Usage

We use the avatar style lorelei in our example. You can find more avatar styles here.

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

const avatar = createAvatar(lorelei, {
  seed: 'John Doe',
  // ... other options
});

const svg = avatar.toString();

Each avatar style comes with several options. You can find them on the details page of each avatar style.

INFO

We provide a large number of avatar styles from different artists. The avatar styles are licensed under different licenses that the artists can choose themselves. For a quick overview we have created an license overview for you.

Methods

createAvatar(style, options)

Return type: Object with .toString(), .toJson() and .toDataUri() methods.

Every cool avatar starts here! An avatar style is expected as the first argument. The second argument is an optional object with options. Which options are possible here depends on the avatar style.

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

const avatar = createAvatar(lorelei, { 
  // ... options
});

.toString()

Return type: string

Returns the avatar as SVG in XML format.

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

const avatar = createAvatar(lorelei, {
  // ... options
});

const svg = avatar.toString(); 

.toJson()

Return type: { svg: string, extra: Record<string, unknown> }

Returns a JSON with the SVG and additional information, such as the actual options used.

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

const avatar = createAvatar(lorelei, {
  // ... options
});

const json = avatar.toJson(); 

.toDataUri()

Return type: Promise<string>

Returns the avatar as data uri.

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

const avatar = createAvatar(lorelei, {
  // ... options
});

const dataUri = avatar.toDataUri();