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/collectionnpm install @dicebear/core @dicebear/collectionTIP
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();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(), .toJson(), .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.
import { createAvatar } from '@dicebear/core';
import { lorelei } from '@dicebear/collection';
const avatar = createAvatar(lorelei, {
// ... options
});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(); 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(); 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 = await avatar.toDataUri(); 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.
import { createAvatar } from '@dicebear/core';
import { lorelei } from '@dicebear/collection';
const avatar = createAvatar(lorelei, {
// ... options
});
const dataUri = avatar.toDataUriSync(); 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.
import { createAvatar } from '@dicebear/core';
import { lorelei } from '@dicebear/collection';
const avatar = createAvatar(lorelei, {
// ... options
});
await avatar.toFile('avatar.svg'); 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.
import { createAvatar } from '@dicebear/core';
import { lorelei } from '@dicebear/collection';
const avatar = createAvatar(lorelei, {
// ... options
});
const arrayBuffer = await avatar.toArrayBuffer(); import { createAvatar } from '@dicebear/core';
import { lorelei } from '@dicebear/collection';
const avatar = createAvatar(lorelei, {
// ... options
});
const arrayBuffer = await avatar.toArrayBuffer(); .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 totrue, the PNG will contain license information in the metadata. By defaultfalse. Only works in Node.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');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.4npm install @resvg/resvg-js@^2.0.0 sharp@^0.30.4The includeExif option requires an additional package:
npm install exiftool-vendored@^16.3.0npm 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 totrue, the JPEG will contain license information in the metadata. By defaultfalse. Only works in Node.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');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.4npm install @resvg/resvg-js@^2.0.0 sharp@^0.30.4The includeExif option requires an additional package:
npm install exiftool-vendored@^16.3.0npm install exiftool-vendored@^16.3.0
