Skip to content
On this page
Sponsor

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.

js
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 designers. The designs are licensed under different licenses that the designers can choose themselves. Some licenses require attribution. For a quick overview we have created an license overview for you.

Methods

createAvatar(style, options)

Return type: Object with .toString(), .toDataUri(), .toFile(name), .toArrayBuffer(), .png(options) and .jpg(options) 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.

js
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.

js
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.

js
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.

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

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

const dataUri = await avatar.toDataUri(); 

.toDataUriSync()

Return type: string

Returns the avatar as data uri. Same as .toDataUri() but synchronous.

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

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

const dataUri = avatar.toDataUriSync(); 

.toFile(name)

Return type: Promise<void>

In browsers, this method downloads the avatar, while in Node.js, the avatar is saved to the file system.

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

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

await avatar.toFile('avatar.svg'); 

.toArrayBuffer()

Return type: Promise<ArrayBuffer>

Converts the avatar to an ArrayBuffer.

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

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

const arrayBuffer = await avatar.toArrayBuffer('avatar.svg'); 

.png(options)

Return type: Object with .toDataUri(), .toFile(name) and .toArrayBuffer() methods.

Converts the avatar from SVG to PNG. Expects an optional options argument of type object. The following options can be passed:

  • includeExif: If set to true, the PNG will contain license information in the metadata. By default false. Only works in Node.js.
js
import { createAvatar } from '@dicebear/core';
import { lorelei } from '@dicebear/collection';

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

const png = await avatar.png({ 
  // ... options
});

// The avatar can now be saved as a PNG, for example.
png.toFile('avatar.png');

Additional dependencies required!

In Node.js, additional packages need to be installed for this method:

npm install @resvg/resvg-js@^2.0.0 sharp@^0.30.4

For the includeExif option, exiftool must be installed and an additional package is needed:

npm install exiftool-vendored@^16.3.0

.jpg(options)

Return type: Object with .toDataUri(), .toFile(name) and .toArrayBuffer() methods.

Converts the avatar from SVG to JPEG. Expects an optional options argument of type object. The following options can be passed:

  • includeExif: If set to true, the JPEG will contain license information in the metadata. By default false. Only works in Node.js.
js
import { createAvatar } from '@dicebear/core';
import { lorelei } from '@dicebear/collection';

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

const jpg = await avatar.jpg({ 
  // ... options
});

// The avatar can now be saved as a JPEG, for example.
jpg.toFile('avatar.jpg');

Additional dependencies required!

In Node.js, additional packages need to be installed for this method:

npm install @resvg/resvg-js@^2.0.0 sharp@^0.30.4

For the includeExif option, exiftool must be installed and an additional package is needed:

npm install exiftool-vendored@^16.3.0