Converter

Sometimes you need the avatar in a different format than SVG. For this we have created a package called @dicebear/converter which can convert the avatar to PNG, JPEG, WebP, and AVIF.

Installation

npm install @dicebear/converter

TIP

You don't need to install the core library @dicebear/core to use the converter package. While it is optimized for DiceBear, it can also be used with SVGs from other sources.

Usage

Although the converter can be used without the core library, we use it in our example to create the avatar.

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

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

const png = toPng(avatar);
const dataUri = await png.toDataUri();

Supported formats

Format	Function	Browser	Node.js	Notes
PNG	toPng	Yes	Yes	Full support
JPEG	toJpeg	Yes	Yes	Full support
WebP	toWebp	Yes*	Yes	Unsupported browsers fall back to PNG
AVIF	toAvif	Yes*	Yes	Unsupported browsers fall back to PNG

* WebP is supported in all modern browsers. AVIF support varies - check caniuse.com for current browser compatibility.

Methods

toPng(svg, options)

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

Converts the avatar from SVG to PNG. Expects an SVG string or an object with toString method as first argument. Expects an optional options argument of type object. See options for more information.

import { toPng } from '@dicebear/converter';

const svg = '<svg>...</svg>';

const png = toPng(svg, {
  // ... options
});

toJpeg(svg, options)

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

Converts the avatar from SVG to JPEG. Expects an SVG string or an object with toString method as first argument. Expects an optional options argument of type object. See options for more information.

import { toJpeg } from '@dicebear/converter';

const svg = '<svg>...</svg>';

const jpeg = toJpeg(svg, {
  // ... options
});

toWebp(svg, options)

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

Converts the avatar from SVG to WebP. Expects an SVG string or an object with toString method as first argument. Expects an optional options argument of type object. See options for more information.

import { toWebp } from '@dicebear/converter';

const svg = '<svg>...</svg>';

const webp = toWebp(svg, {
  // ... options
});

Limited browser support

This function uses an HTML canvas element in the browser and is dependent on the browser being able to export the canvas as WebP. If the browser does not support WebP, PNG is used as a fallback. See MDN web docs for browser compatibility.

toAvif(svg, options)

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

Converts the avatar from SVG to AVIF. Expects an SVG string or an object with toString method as first argument. Expects an optional options argument of type object. See options for more information.

import { toAvif } from '@dicebear/converter';

const svg = '<svg>...</svg>';

const avif = toAvif(svg, {
  // ... options
});

Limited browser support

This function uses an HTML canvas element in the browser and is dependent on the browser being able to export the canvas as AVIF. If the browser does not support AVIF, PNG is used as a fallback. See MDN web docs for browser compatibility.

.toDataUri()

Return type: Promise<string>

Returns the image as a data URI. This is useful for embedding the image directly in HTML or CSS.

import { toPng } from '@dicebear/converter';

const svg = '<svg>...</svg>';

const png = toPng(svg, {
  // ... options
});
const dataUri = await png.toDataUri(); 

// Use in HTML: <img src={dataUri} alt="Avatar" />

.toArrayBuffer()

Return type: Promise<ArrayBuffer>

Converts the image to an ArrayBuffer. This is useful for saving files or sending binary data.

import { toPng } from '@dicebear/converter';

const svg = '<svg>...</svg>';

const png = toPng(svg, {
  // ... options
});
const buffer = await png.toArrayBuffer(); 

Options

Option	Type	Default	Environment	Description
size	number	512	Browser + Node.js	Output image size in pixels (max: 2048)
fonts	string[]	[]	Node.js	Paths to custom font files
includeExif	boolean	false	Node.js	Include metadata in output image

size ^9.4.0

Type: number

Default: 512

Maximum: 2048

Controls the width and height of the rasterized output image in pixels. The output is always square. Values above 2048 are clamped to 2048. Invalid values (NaN, <= 0, Infinity) fall back to 512.

Breaking change in v9.4.0

Before v9.4.0, the output image size was derived from the SVG's width and height attributes. The output size is now always controlled by the size option and no longer read from the SVG itself.

import { toPng } from '@dicebear/converter';

const png = toPng(svg, {
  size: 128,
});

fonts Node.js only

Type: string[]

Default: []

An array of paths to font files which should be used to render the avatar. If not set, the system fonts will be used. This is particularly useful for the initials style or other styles that render text.

import { toPng } from '@dicebear/converter';

const png = toPng(svg, {
  fonts: ['/path/to/custom-font.ttf'],
});

includeExif Node.js only

Type: boolean

Default: false

If set to true, the converter will try to read the metadata from the SVG and add it to the output image as Exif metadata. This is useful for preserving license and attribution information.

The following metadata is extracted and embedded:

• Title - Avatar style title
• Source - Source URL
• Creator - Artist/creator name
• License - License information
• Copyright - Copyright notice

import { toPng } from '@dicebear/converter';

const png = toPng(svg, {
  includeExif: true,
});

WARNING

This uses an exiftool singleton which needs to be exited manually when your application terminates. See the exiftool-vendored documentation for more information.

import { exiftool } from 'exiftool-vendored';

// When your application exits:
await exiftool.end();

Examples

Convert DiceBear avatar to PNG

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

const avatar = createAvatar(lorelei, {
  seed: 'John Doe',
  backgroundColor: ['b6e3f4'],
});

const png = toPng(avatar);
const dataUri = await png.toDataUri();

// Use in browser
document.querySelector('img').src = dataUri;

Save avatar to file (Node.js)

import { createAvatar } from '@dicebear/core';
import { bottts } from '@dicebear/collection';
import { toPng } from '@dicebear/converter';
import { writeFile } from 'node:fs/promises';

const avatar = createAvatar(bottts, {
  seed: 'robot-42',
});

const png = toPng(avatar);
const buffer = await png.toArrayBuffer();

await writeFile('avatar.png', Buffer.from(buffer));

Convert with Exif metadata (Node.js)

import { createAvatar } from '@dicebear/core';
import { lorelei } from '@dicebear/collection';
import { toPng } from '@dicebear/converter';
import { exiftool } from 'exiftool-vendored';
import { writeFile } from 'node:fs/promises';

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

const png = toPng(avatar, {
  includeExif: true,
});

const buffer = await png.toArrayBuffer();
await writeFile('avatar.png', Buffer.from(buffer));

// Important: Close exiftool when done
await exiftool.end();

Use with custom fonts (Node.js)

import { createAvatar } from '@dicebear/core';
import { initials } from '@dicebear/collection';
import { toPng } from '@dicebear/converter';

const avatar = createAvatar(initials, {
  seed: 'John Doe',
});

const png = toPng(avatar, {
  fonts: ['/path/to/Roboto-Bold.ttf'],
});

const dataUri = await png.toDataUri();

Convert with a custom size

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

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

const png = toPng(avatar, { size: 128 });
const dataUri = await png.toDataUri();

Convert any SVG (without DiceBear)

import { toPng } from '@dicebear/converter';

const svg = `
  <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
    <circle cx="50" cy="50" r="40" fill="red" />
  </svg>
`;

const png = toPng(svg);
const dataUri = await png.toDataUri();

TypeScript

The library is fully typed:

import { toPng, toJpeg, toWebp, toAvif } from '@dicebear/converter';
import type { Options, Result } from '@dicebear/converter';

const options: Options = {
  includeExif: true,
};

const result: Result = toPng(svg, options);
const buffer: ArrayBuffer = await result.toArrayBuffer();