README (README.md)

<h1><img src="https://www.dicebear.com/logo-readme.svg" width="28" /> DiceBear Avatar Library</h1>

[](https://www.npmjs.com/package/@dicebear/core)
[](https://github.com/dicebear/dicebear/stargazers)
[](./LICENSE)

DiceBear is an open source avatar library. It turns any seed string (a username
or an email address, for example) into an SVG avatar in one of 52 styles, from
hand-drawn characters to abstract patterns. The same seed always produces the
same avatar, so you store a string instead of an image and never ask users to
upload a profile picture.

Avatars are customizable through style options: colors, backgrounds, rotation,
individual features like hair or glasses.

Playground |
Documentation |
Editor

One library, six languages

DiceBear 10 ships as native libraries for JavaScript, PHP, Python, Rust, Go, and
Dart. Every port passes a shared test suite that requires byte-identical SVG
output to the JavaScript reference. Generate an avatar in the browser,
regenerate it later in a Go or PHP backend, and you get the same bytes.

| Language | Package | Install |
| ----------------------- | ----------------------------------------------------------------------- | -------------------------------------------- |
| JavaScript / TypeScript | @dicebear/core | npm install @dicebear/core |
| PHP | dicebear/core | composer require dicebear/core |
| Python | dicebear-core | pip install dicebear-core |
| Rust | dicebear-core | cargo add dicebear-core |
| Go | dicebear-go | go get github.com/dicebear/dicebear-go/v10 |
| Dart | dicebear_core | dart pub add dicebear_core |

In JavaScript it looks like this; the
documentation has the equivalent for
each language:

import { Avatar } from '@dicebear/core';
import definition from '@dicebear/styles/lorelei.json' with { type: 'json' };
const avatar = new Avatar(definition, {
  seed: 'John Doe',
  size: 128,
});avatar.toString(); // SVG string
avatar.toDataUri(); // data:image/svg+xml;charset=utf-8,...

The 52 avatar styles are plain JSON definitions from the
dicebear/styles repository, available as
a package for each language. You can also
create your own style,
with Figma or from scratch.

Without writing code

- The HTTP API returns avatars
from a plain URL, free and without an account:
https://api.dicebear.com/10.x/lorelei/svg?seed=Felix. For full control and
privacy you can
host it yourself
with a single Docker container.
- The CLI generates avatar files in
bulk: npx dicebear lorelei --count 10.
- The editor lets you assemble a single avatar by
hand and export it.

This repository

This monorepo contains the six core libraries, the CLI, the SVG-to-raster
converter, the documentation site (dicebear.com),
and the editor. Related projects live in their own repositories:

- dicebear/styles: the official avatar
style definitions
- dicebear/schema: the JSON Schema
behind definitions and options
- dicebear/api: the self-hostable HTTP API
- dicebear/exporter-plugin-for-figma:
the Figma plugin for style authors

Contributions are welcome; CONTRIBUTING.md explains the
setup and where each kind of change belongs.

License

The code is MIT licensed, including commercial use. The avatar
styles are the work of their respective creators and carry their own licenses;
the license overview lists them all, and
many only ask for attribution.

Star this repository

If DiceBear saved you some work, a star makes the project easier to find for the
next person looking for an avatar library. The
support page lists the other ways to help.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to
Semantic Versioning.

[Unreleased]

Added

- Core: Color fields in OptionsDescriptor now carry notEqualTo, the list
of color groups a group must differ from, next to the existing contrastTo,
in all six core implementations (JavaScript, PHP, Python, Rust, Go, and Dart).
Tooling that picks colors itself needs both constraints, because one explicit
color per group leaves the renderer nothing to sort or filter. The descriptor
parity fixtures and the guide on accessing all available options cover the new
property.

Fixed

- Editor: Shuffle drew every color on its own and ignored the contrastTo
and notEqualTo constraints from the style definition. In thumbs that gave
the shape the background color in about one of five shuffles, where it then
vanished, and picked the worse of black and white for eyes and mouth about
half the time. clay, critters, micah, voxel-art, and voxel-bot were
affected too. Shuffle now resolves colors in dependency order and applies the
same constraints as the renderer.

[10.5.0] - 2026-08-09

Added

- Core: New per-color option *ColorOrder with the values random and
fixed, in all six core implementations (JavaScript, PHP, Python, Rust, Go,
and Dart). random is the previous behavior: the PRNG shuffles the colors
before use. With fixed, colors passed via *Color keep exactly the given
order; gradient fills apply them as stops from first to last, solid fills
always use the first color, and the number of gradient stops defaults to the
number of given colors. Without user-supplied colors, fixed only skips the
shuffle and uses the style's palette in sorted order; contrastTo and
notEqualTo constraints still apply, so referenced color groups can keep the
result seed-dependent. Existing avatars are unaffected, since random stays
the default. Requested in discussion
#549 for building
gradients with a fixed color sequence, such as flag colors. @dicebear/schema
1.4.0 validates the option, and two new parity fixture cases per style pin its
behavior across the ports. The core options guide and the implementation
specification cover the details.
- Docs: Style pages for voxel-art and voxel-bot, the two styles new in
@dicebear/styles 10.4.0. The animated-avatars page now fills its style count
from the definitions at build time, through the same token mechanism the
overall count already uses; the hardcoded number it replaces had gone stale
at 15.
- Editor: The eight character styles the editor was missing: clay,
critters, moods, pixelbot, sprouts, thumbs, voxel-art, and
voxel-bot. Its style list now matches the docs' Characters category exactly,
and the new option labels are translated into English, German, and Portuguese.
The animation option stays hidden in the editor, since its export writes
static files; an avatar without an explicit animationVariant never animates,
because every animated variant carries weight 0.

Changed

- Core (JavaScript): The schema validators are now generated with
@exodus/schemasafe instead
of Ajv. The published package still has no runtime dependencies, and the
validator code shrinks from 164 KB to 114 KB minified, so browser bundles of
@dicebear/core shrink by the same amount. Both compilers accept and reject
the same inputs: every published style definition and a set of deliberately
broken samples produced identical verdicts. Error messages change, however.
schemasafe reports JSON pointers without prose, so the message is now derived
from the failing keyword (/size is smaller than allowed), and every
ValidationErrorDetail carries two new optional fields, schemaPath and
keyword, that name the schema rule behind a failure. When an object violates
a named property and a pattern property at the same time, the error list only
reports the first group; the verdict is not affected.
- CLI: Removed the unused ajv dependency, which makes a CLI install about
2.7 MB smaller.
- Converter: The browser build no longer bundles an XML parser. Setting the
render size and mirroring mask-type declarations now run on the native
DOMParser and XMLSerializer, which every browser ships. The XML dependency
stack (fast-xml-parser and friends) made up nine tenths of the browser bundle;
it stays in the Node build, where no native XML machinery exists. A browser
bundle of @dicebear/converter shrinks from 26 kB to 1.4 kB gzipped. Two
edges change with the parser: a malformed SVG now fails with a clear error
instead of a parser-specific one, and when normalizeMaskType rewrites a
document in the browser, empty elements come back self-closing. Both helpers
are covered by new jsdom-based tests.
- Styles: Bumped @dicebear/styles to 10.4.0 for the CLI, the docs, and
the editor. The release adds voxel-art and voxel-bot, which take the
collection from 50 to 52 styles. Both ship the opt-in animation component,
so 18 of the 52 styles can now animate.

Deprecated

- Core: The sorted fallback order that *ColorOrder: 'fixed' applies when
no *Color option is set. In DiceBear 10, this case deduplicates and
code-point sorts the style palette, so palettes keep their canonical order and
only the shuffle is skipped. DiceBear 11 will use the palette in its
definition order instead, the same verbatim rule that already applies to
user-supplied colors. That removes the user-colors/palette distinction from
the resolvers and makes fixed mean the same thing for both sources. The sort
site in each of the six ports carries a matching deprecation comment.

Fixed

- Docs: The bundle size estimator now reports what a bundler actually ships:
one minified bundle per package, gzipped as a whole. It previously gzipped
every published file on its own without minification, which showed
@dicebear/core at 58 kB instead of 26 kB and @dicebear/converter at 8 kB
instead of 26 kB, since the converter's browser build pulls its XML
dependencies into the bundle. The converter hint also claimed PDF output; the
package converts to PNG, JPEG, WebP, and AVIF.

[10.4.0] - 2026-08-01

Changed

- Styles: Bumped @dicebear/styles to 10.3.0. The release adds thirteen
styles: blobs, clay, constellation, critters, landscape, loops,
moods, pixelbot, planets, sprouts, squircles, waves, and weave.
It also gives shapes, glass, thumbs, initial-face, and every new style
except weave an opt-in animation component, which stays off until the
animationVariant or tags render option turns it on.

[10.4.0-rc.2] - 2026-07-31

Fixed

- Converter: Raster conversion no longer drops parts of rotated avatars with
translucent layers. The resvg build that resvg-js bundles places the
isolation layer of an opacity group in the wrong coordinate space when the
group sits under both a clip-path and a large rotation, and cuts the group's
content. The waves style lost about half of its image in every raster
format, including through the HTTP API. Since the viewport crops to the canvas
anyway, the converter now removes clip paths that cover exactly the canvas
before it hands the SVG to resvg. A clip with rounded corners is removed as
well and re-applied to the rendered image, so the radius option keeps
working. Its corners are drawn by sharp instead of resvg as a result, which
changes their antialiasing slightly.

[10.4.0-rc.1] - 2026-07-31

Added

- Core (all languages): A new tags render option narrows the pool of
variants an avatar is drawn from. Styles may label their variants with tags
such as animation or hairLength:long, and the option keeps or drops
variants by those labels, so one trait is pinned down while the rest of the
avatar stays varied. A token is category or category:value, with a leading
! to exclude. An include keeps the variants carrying a matching tag together
with those that carry no tag in the category. Several values of one category
act as "or", different categories act as "and", and an exclude wins over an
include. A bare category token requires the category and drops the variants
without a tag in it, but only in the components where the category is in use.
An unknown category is ignored, an unknown value is not: since nothing matches
it, every variant tagged in that category drops out. A per-component
{component}Variant option is more specific and switches the filter off for
that component. If a filter leaves a component without a variant, the
component is not drawn. The option takes a string or an array of strings, and
in the HTTP API it is the comma-separated tags query parameter. Styles that
carry no tags are unaffected. In the DiceBear styles, tags currently describe
one thing, the opt-in animation of the animated styles, so tags=animation
turns that animation on at a random speed per seed and !animation keeps it
off. The character categories follow in a later release.
- Docs: Two guides cover the new option, "Filter Avatar Variants with Tags"
for the filter itself and "How DiceBear Tags Variants" for the vocabulary the
DiceBear styles use. The playground has a tag panel per category, where every
token is an allow/disallow switch, and its count of unique avatars accounts
for the filter. Style pages list the tags a style provides and mark every
variant preview with its own. The core option reference moved out of the
JavaScript page onto a shared "Core options" page that all six library pages
link to.
- CLI: Definition files can now be compressed in place with
dicebear ./my-style.json --optimize. The flag runs the same svgo pass over
every element tree that the current Figma exporter applies on export.
Hand-authored definitions and files from older exporter versions shrink, by up
to 42% (pixel-art), while recent exports come back unchanged.
--optimize-check reports without writing and exits non-zero when the file
would change, which makes it usable as a CI gate. --optimize-precision sets
the float precision for path and transform data (default 3). Color and
component references, variables, element ids, CSS classes and <style>
contents are verified after the pass, and the CLI refuses to write the file
when any of them changed.

Fixed

- Core (all languages): The id suffix for <defs> entries now hashes the
style source name together with the seed. It previously hashed only the seed,
so two avatars of different styles with the same seed produced identical ids
for shared component names (body, eyes, animation, clip, ...) and
stole each other's <defs> when inlined on one page. Rendered ids change for
every avatar as a result.
- Core (all languages): The generator comment now points at
https://www.dicebear.com. It carried the bare dicebear.com host since
10.3.0, which only redirects to the canonical www host that the <metadata>
block already used. The byte output of every avatar changes as a result,
including data URIs and content hashes, so consumers that compare rendered
SVGs against stored snapshots need to update them.
- Docs: In the playground, clicking "None" in a component's variant picker
while weights were shown stored an empty weights object, which the core
rejects — the preview then rendered no avatar at all. An empty selection is
now stored as an empty list, which renders the avatar without that component.
Styles that ship non-default weights were affected immediately, because their
pickers open in weights mode.

[10.3.2] - 2026-07-29

Fixed

- Converter: Raster conversion no longer alters text content. The XML round
trip that sets the output size trimmed whitespace and converted
numeric-looking text, so <text>0123</text> rendered as 123 and 1e3 as
1000 in every raster format, including through the HTTP API. Text nodes and
CDATA sections now survive the round trip unchanged. Previously the converter
unwrapped a CDATA section into raw text, which could turn a valid SVG into
ill-formed XML.
- Converter: Raster conversion now accepts SVGs nested deeper than 100
elements. The XML parser's default nesting cap made toPng() and friends
throw on valid documents that resvg renders fine. The cap is now 1024 levels.
- Converter: The converter now reads mask-type declarations the way a
browser does. It strips a trailing !important instead of copying it into the
presentation attribute, where resvg would reject the value and silently fall
back to luminance. It ignores invalid values, and when a style attribute
repeats the declaration, the last valid one wins.

Changed

- Converter: normalizeMaskType() now works on the parsed XML tree instead
of rewriting the markup with regular expressions, and the raster entry points
apply it in the same parser pass that sets the output size. Input that needs
no fix comes back byte-identical. So does input the XML parser cannot read,
where the old version attempted a partial rewrite. When a mask does need
fixing, the function re-emits the SVG from the parsed tree, which can
normalize formatting details such as quote style or self-closing tags and
drops a <!DOCTYPE> declaration. The rendered image stays the same.
- Converter: The XML serializer moved from the deprecated XMLBuilder
export of fast-xml-parser to its successor package fast-xml-builder. The
output is byte-identical. The only visible change for consumers is the new
package in the dependency tree.

[10.3.1] - 2026-07-27

Fixed

- Converter: Masks that declare mask-type: alpha in a style attribute
now rasterize correctly. resvg reads mask-type only as a presentation
attribute, and without one it falls back to the luminance default, which
turns a mask drawn in black into a mask that hides its subject. Seven styles
ship such masks: bottts-neutral, disco, glyphs, lorelei, micah,
personas and toon-head. On lorelei a bearded avatar lost its mouth in
the PNG while the SVG rendered fine. The HTTP API converts through this
package and was affected the same way. The normalization is also exported as
normalizeMaskType() for callers that drive resvg directly.

[10.3.0] - 2026-06-13

Added

- Core: Every rendered SVG now starts with the generator comment
`as the first child of the root<svg>element. The comment is byte-identical across the JavaScript, PHP, Python, Rust, Go, and Dart libraries. The byte output of every avatar changes as a result, including data URIs and content hashes, so consumers that compare rendered SVGs against stored snapshots need to update them. SVG optimizers that strip comments (e.g. SVGO with default settings) remove it again. - Dart library: A new Dart implementation (thedicebear_corepackage) that produces identical output to the JavaScript library when given the same styles and options. It validates style definitions and options against the shared schemas (viadicebear_schema) and pairs with the dicebear_stylespackage. - Core (PHP, Python): AddedStyle::fromJson()(PHP) andStyle.from_json()(Python) to build a style from a raw JSON string without a separatejson_decode(..., true) / json.loads(...)call. Malformed JSON raises the language's native parse error (JsonException/json.JSONDecodeError); an invalid definition raises the usualStyleValidationError. Mirrors Style::from_str (Rust) and Style.parse(Dart); the existing array/dict constructor is unchanged.

`Deprecated`

- Core (JS, PHP, Python): Passing a raw style definition to Avataris deprecated; pass aStyleinstead (new Avatar(new Style(definition), options)), which also lets you reuse one parsed style across many avatars. The definition still works for now and renders identically, but emits a deprecation warning (a one-timeconsole.warn in JS, E_USER_DEPRECATED in PHP, DeprecationWarningin Python) and will be removed in v11. The Dart, Rust and Go libraries already require aStyle, so this brings every port to the same Avatar(style, …)call.

`[10.2.0] - 2026-06-10`

`Added`

- Go library: A new Go implementation (thegithub.com/dicebear/dicebear-go/v10module) that produces identical output to the JavaScript library when given the same styles and options.

`Fixed`

- Core: Color.luminance()now derives the sRGB linearization from a precomputed lookup table (one entry per 8-bit channel value) instead of callingpow at runtime. powis not required to be correctly rounded and produced last-ULP differences between JS engines (V8 vs. others), the C math library (PHP, Python, Rust), and Go's pure-Go implementation, so luminance values, and in contrived cases contrast-based color ordering, could diverge across languages and even across browsers. The table holds the values the JavaScript reference produces today, so JavaScript output is unchanged; the other libraries move by at most one ULP. The Go library additionally forces intermediate rounding in the weighted sum, which the compiler could otherwise fuse into FMA instructions on arm64. Rendered SVGs are unaffected. - Core (PHP):Avatar::toDataUri()now percent-encodes exactly like JavaScript'sencodeURIComponent. Previously the PHP library used plainrawurlencode, which additionally escapes !*'(), characters that occur in every rendered SVG (e.g.url(#…) references and translate(…)transforms), so the data URI diverged byte-wise from the JavaScript, Python, Rust, and Go libraries. The decoded SVG was unaffected. - Core (JS): Theinitialstyle variable now resolves to the full first code point of the initials. Previously the JavaScript library emitted a lone UTF-16 surrogate (ill-formed XML) when the initials started with a character outside the Basic Multilingual Plane (e.g. an emoji). The PHP, Python, Rust, and Go libraries already returned the full character; all libraries are now byte-identical for such seeds. - Core (Rust):Avatar.to_json() now records size before titlein the resolved-options snapshot, matching the JavaScript, PHP, and Python libraries. The rendered SVG was unaffected; only consumers comparing or hashing the serialized options JSON across languages were affected. - Core (Python):Avatar.to_json()now serializes whole-number floats in the resolved-options snapshot as integers (1, not 1.0), matching the JavaScript, Rust, and PHP libraries. Previously snapshot values such asscale, rotate, translateX/translateY, borderRadius, color angles, and per-component transforms were emitted as1.0/0.0, so the serialized JSON diverged from the other ports. The rendered SVG was unaffected. The values were already numerically equal, so only consumers comparing or hashing the serialized options JSON across languages were affected.

`[10.2.0-rc.1] - 2026-06-07`

`Added`

- Rust library: A new Rust implementation (the dicebear-corecrate) that produces identical output to the JavaScript library when given the same styles and options.

`Fixed`

- Core: Initials now discard everything from the first @to the end of the seed (e.g. an email domain). Previously the strip stopped at the first line terminator (at a line feed in PHP and Python, and additionally at a carriage return orU+2028/U+2029in JavaScript), so a seed with a line break after the@kept the trailing text as a second word, and the libraries could even diverge from each other. All language libraries now produce byte-identical initials for such seeds.

`[10.1.0] - 2026-06-06`

`Changed`

- Schema: Bumped the bundled @dicebear/schema to 1.1.0across the JavaScript, PHP, and Python libraries. It adds an upper bound of1000000to the canvas and componentwidth/height, preventing the language ports' number-to-string formatting from diverging at extreme values. Official styles use ~100, so no real avatar is affected. - Styles: Bumped@dicebear/styles to 10.1.0. Lorelei's mouth is now visible throughbeardvariants (the overlaying mask was previously rendered at0opacity), and all style definitions now reference@dicebear/[email protected].

`[10.1.0-rc.1] - 2026-06-02`

`Added`

- Python library: A new Python implementation that produces identical output to the JavaScript library when given the same styles and options.

`[10.0.2] - 2026-06-02`

`Fixed`

- Core: Numeric values in rendered SVGs are now consistently rounded to at most 5 decimal places, so the JavaScript and PHP libraries produce byte-identical output for every input. Previously, fractional or very small/large values (e.g. a fractionalborderRadius or translateX, component transforms, or gradient stop offsets) could be stringified differently between languages (scientific notation, differing precision). Avatars built from whole-number options are unaffected. - Core (PHP):Prng::floatnow rounds halves toward +Infinity (matching the JavaScript reference'sMath.round) instead of PHP's native round(), which rounds halves away from zero. The two diverged for negative values landing exactly on a.5boundary, so a PHP-rendered avatar could differ from the JavaScript one by0.0001in a rotate/translate transform or color angle for certain seeds. Output is now byte-identical across languages. - Core (PHP): Initials are now derived correctly from seeds containing multibyte letters such asü or ô. The quote-stripping step was missing the/u(Unicode) flag, so it removed raw UTF-8 bytes and corrupted those letters: e.g.über and côtéproduced wrong or empty initials instead ofÜB / CÔ. The PHP output now matches the JavaScript reference. - Core: Range options (scale, borderRadius, rotate,translateX/translateY, and per-color angle/fill-stops) given as a single-element array[n] are now treated as the fixed value n(identical to the scalarn), and an empty array []falls back to the option's default. Both forms are permitted by the schema. Previously the behavior diverged: the JavaScript library emittedNaN (e.g. scale(NaN)), while PHP dropped[n] to the default. All three now agree.

`[10.0.1] - 2026-05-29`

`Fixed`

- CLI: dicebear --version and dicebear --helpno longer fail by trying to read a file named--version/--help. The definition path is now resolved via the argument parser, so flags (and the values they consume) before the path are handled correctly, e.g.dicebear --json my-style.jsonanddicebear --count 2 my-style.json.

`[10.0.0] - 2026-05-27`

See the v10.0.0 release notes.

`Added`

- 6 new avatar styles: Disco, Glyphs, Initial Face, Shape Grid, Stripes, and Triangles. - PHP library: A new PHP implementation that produces identical output to the JavaScript library when given the same styles and options. - CLI support for custom styles: Generate avatars from a JSON style definition, e.g.dicebear ./path/to/style.json --seed test --format svg. - Weighted variants: Assign weights to component variants to control how frequently each appears. - Gradient support: Colors can be defined as gradients, including an angle parameter. - Integrated validation: Built-in validation for avatar styles and options. - Redesigned playground: Adjust options, upload custom styles, batch download avatars, and view the number of possible combinations. - New tools: WCAG Contrast Picker and Bundle Size Estimator. - Reorganized and improved documentation, with better style docs and component previews.

`Changed`

- Each avatar style is now stored as a JSON definition file instead of JavaScript code, separating licensing concerns from implementation. - Styles are now distributed via@dicebear/stylesas JSON definitions. - The JavaScript API now usesStyle and Avatarclasses together with definition imports. - BREAKING: Component options are now suffixed withVariant(e.g.eyesVariant instead of eyes).

`Removed`

- BREAKING: Individual style packages (e.g. @dicebear/initials) have been removed in favor of@dicebear/styles.

[Unreleased]: https://github.com/dicebear/dicebear/compare/v10.5.0...HEAD [10.5.0]: https://github.com/dicebear/dicebear/compare/v10.4.0...v10.5.0 [10.4.0]: https://github.com/dicebear/dicebear/compare/v10.4.0-rc.2...v10.4.0 [10.4.0-rc.2]: https://github.com/dicebear/dicebear/compare/v10.4.0-rc.1...v10.4.0-rc.2 [10.4.0-rc.1]: https://github.com/dicebear/dicebear/compare/v10.3.2...v10.4.0-rc.1 [10.3.2]: https://github.com/dicebear/dicebear/compare/v10.3.1...v10.3.2 [10.3.1]: https://github.com/dicebear/dicebear/compare/v10.3.0...v10.3.1 [10.3.0]: https://github.com/dicebear/dicebear/compare/v10.2.0...v10.3.0 [10.2.0]: https://github.com/dicebear/dicebear/compare/v10.2.0-rc.1...v10.2.0 [10.2.0-rc.1]: https://github.com/dicebear/dicebear/compare/v10.1.0...v10.2.0-rc.1 [10.1.0]: https://github.com/dicebear/dicebear/compare/v10.1.0-rc.1...v10.1.0 [10.1.0-rc.1]: https://github.com/dicebear/dicebear/compare/v10.0.2...v10.1.0-rc.1 [10.0.2]: https://github.com/dicebear/dicebear/compare/v10.0.1...v10.0.2 [10.0.1]: https://github.com/dicebear/dicebear/compare/v10.0.0...v10.0.1 [10.0.0]: https://github.com/dicebear/dicebear/releases/tag/v10.0.0

---

`CONTRIBUTING (CONTRIBUTING.md)`

`Contributing`

Thanks for your interest in contributing to DiceBear.

This is the main monorepo: the JavaScript, PHP, Python, Rust, Go, and Dart core libraries, the CLI, the docs site, and the editor all live here. Repositories covering the JSON Schema, the avatar style definitions, the HTTP API, and the Figma exporter are separate and each have their ownCONTRIBUTING.md:

- dicebear/schema: JSON Schema for definitions and options -dicebear/styles: Official avatar style definitions -dicebear/api: Self-hostable HTTP API -dicebear/exporter-plugin-for-figma: Figma plugin

If your contribution belongs to one of those repos, read its file first. The instructions below only cover this monorepo.

`Before you start`

- Bug fixes, small improvements, new tests: open a pull request against the branch that matches the target major (for DiceBear 10 that's10.x; the current stable line lives on9.x). - New avatar styles: contribute them todicebear/styles, not here. The walkthrough is in Create an avatar style with Figma or Create an avatar style from scratch. - Larger changes (new public API, rendering behavior, breaking changes): open an issue first so we can agree on scope before you spend time on it. - Security issues go privately to <[email protected]>; never file a public issue for a vulnerability. - Contributors follow the DiceBear Code of Conduct.

`Requirements`

- Node.js 20 or newer (CI runs on 20, 22, 24, 25) - npm 11 (this repo pinspackageManager in package.json; use Corepack if you don't already) - For PHP work: PHP 8.2+ and Composer, plusvendor/bin/phpunitviacomposer install inside src/php/core/- For Python work: Python 3.10+ (CI runs on 3.10 to 3.14); install the package in a virtualenv withpip install -e ".[dev]" inside src/python/core/- For Rust work: Rust 1.80+ with theclippy and rustfmtcomponents; build and test withcargo test, cargo clippy, and cargo fmtinsidesrc/rust/core/- For Go work: Go 1.23+ (CI runs on 1.23 to 1.25); test withgo test ./...and check withgofmt -l . and go vet ./... inside src/go/core/- For Dart work: Dart SDK 3.4+ (CI runs on 3.4 and stable); test withdart test and check with dart format --output=none --set-exit-if-changed .anddart analyze --fatal-infos inside src/dart/core/

`Local setup`

sh

git clone [email protected]:dicebear/dicebear.git
cd dicebear
npm install

The monorepo uses npm workspaces (src/js/ and apps/) driven by Turborepo. A single install at the root is enough; do notnpm install inside individual packages.

`Common scripts`

Run these from the repo root:

| Script | What it does | | ---------------------- | --------------------------------------------------- | |npm run build| Builds every workspace via Turbo | |npm test| Runs every workspace's test target | |npm run test:scripts | Runs the repo-level scripts in tests//*.test.js| |npm run lint| Runs ESLint across the repo with caching | |npm run lint:fix | Same, with --fix| |npm run prettier | Formats src/ and apps/ with Prettier |

For faster loops, scope to a single workspace:

sh

npm run build --workspace @dicebear/core
npm run test  --workspace @dicebear/core

`Repository layout`

text

src/
├── js/              # TypeScript packages published to npm
│   ├── core/          # Rendering engine (@dicebear/core)
│   ├── cli/           # Command-line interface
│   └── converter/     # SVG → raster converter
├── php/             # PHP port (Composer package dicebear/core)
├── python/          # Python port (PyPI package dicebear-core)
├── rust/            # Rust port (crates.io crate dicebear-core)
├── go/              # Go port (module github.com/dicebear/dicebear-go/v10)
└── dart/            # Dart port (pub.dev package dicebear_core)
apps/
├── docs/            # VitePress documentation site (dicebear.com), including the Playground
└── editor/          # The in-browser editor (editor.dicebear.com)
tests/
└── fixtures/parity/ # Cross-language parity fixtures (see below)
scripts/
└── version.mjs      # Bumps versions across the workspace and tags

`Working on a package`

`TypeScript packages (`src/js/`)`

sh

npm run build --workspace <package>
npm run test  --workspace <package>

If you are working on the CLI, call the compiled script directly once you've built it:

sh

node src/js/cli/bin/index.js <command>

`PHP core (`src/php/core/`)`

sh

cd src/php/core
composer install
vendor/bin/phpunit

`Python core (`src/python/core/`)`

sh

cd src/python/core
pip install -e ".[dev]"   # in a virtualenv
ruff check .
ruff format --check .
mypy src
pytest

The Python core reads the two draft-07 schemas from the dicebear-schemapackage (the Python counterpart of@dicebear/schema / dicebear/schema), whichpip install -e ".[dev]"pulls in as a runtime dependency. Nothing is vendored.

`Rust core (`src/rust/core/`)`

sh

cd src/rust/core
cargo test
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --check

The Rust core reads the two draft-07 schemas from the dicebear-schemacrate (the Rust counterpart of@dicebear/schema / dicebear/schema) as a runtime dependency. Nothing is vendored.

`Go core (`src/go/core/`)`

sh

cd src/go/core
go test ./...
go vet ./...
gofmt -l .   # prints nothing when formatting is correct

The Go core reads the two draft-07 schemas from the github.com/dicebear/schemamodule (the Go counterpart of@dicebear/schema / dicebear/schema) as a dependency. Nothing is vendored. Style definitions come fromgithub.com/dicebear/styles/v10. The module path carries the major version (/v10), so a major bump changes the path by hand; scripts/version.mjsonly creates the Git tag the module proxy reads.

`Dart core (`src/dart/core/`)`

sh

cd src/dart/core
dart pub get
dart test
dart analyze --fatal-infos
dart format --output=none --set-exit-if-changed .

The Dart core reads the two draft-07 schemas from the dicebear_schemapackage (the Dart counterpart of@dicebear/schema / dicebear/schema) as a runtime dependency, validated withpackage:json_schema. Nothing is vendored.

src/dart/core/CHANGELOG.mdis a git-ignored build artifact: pub.dev expects a changelog inside the package directory, so the CI workflows copy the repository rootCHANGELOG.md there before dart pub publish [--dry-run]. This follows the same pattern as the generatedLICENSEcopies in the styles and schema repositories. Maintain the root changelog only.

`Cross-language parity`

Every port must produce output byte-identical to the reference JavaScript core (@dicebear/core) for the same inputs. A shared fixture suite intests/fixtures/parity/(generated from the JS reference) enforces this, and each side consumes it:

- JS side: src/js/core/tests/Parity.test.js, run vianpm run test --workspace @dicebear/core. - PHP side:tests/ParityTest.php, run via vendor/bin/phpunitinsrc/php/core/. - Python side:tests/test_parity.py, run via pytest in src/python/core/. - Rust side: the module unit tests plustests/avatars.rs, run via cargo testinsrc/rust/core/. - Go side: the in-package tests (parity_test.go, avatars_test.go), run viago test ./... in src/go/core/. - Dart side: the tests undertest/parity/, run via dart testinsrc/dart/core/.

The fixtures cover Fnv1a (hash + hex), Mulberry32(chained sequences), everyPrng method, number-to-string formatting (numbers.json, the formatNumbercontract: every emitted number rounded to at most 5 decimal places, which every port must reproduce identically), initials extraction, theColorhelpers (including bit-exact luminance doubles), accept/reject validation outcomes plus circular color-reference chains, theOptionsDescriptorfield map, and fullAvatar.toString() (plus selected toDataUri()) output for the initials,thumbs, glass, notionists, and shape-gridstyles. That last bucket covers seed, size, transforms, gradients,titleescaping, and component-variant overrides.

Float determinism is part of the parity contract: powis not correctly rounded (JS engines, libm, and Go all differ in the last bit), so the sRGB linearization ships as a precomputed 256-entry table in every port, and languages that fuse multiply-add into FMA instructions (e.g. Go on arm64) must force intermediate rounding. The details live in the Implement DiceBear Core spec.

If your change affects rendering or the PRNG in @dicebear/core, regenerate the fixtures from the JS reference and commit the diff:

sh

npm run fixtures:parity

The PHP, Python, Rust, Go, and Dart suites will then fail loudly until those sides are brought back in sync. That is the intended signal. If you only intend to touch one language, expect to update both before your PR can be merged.

When porting DiceBear to another language, run these fixtures against your implementation to prove it conforms. See Implement DiceBear Core for the full spec.

`Documentation changes (`apps/docs/`)`

The docs site is a VitePress app under apps/docs/.

sh

npm run dev --workspace @dicebear/docs    # live reload on localhost
npm run build --workspace @dicebear/docs  # production build check

For larger editorial changes, open a draft PR early so reviewers can follow along.

`Editor changes (`apps/editor/`)`

The editor is the standalone app served at editor.dicebear.com.

sh

npm run dev --workspace @dicebear/editor
npm run build --workspace @dicebear/editor

`Code style`

- ESLint and Prettier decide what counts as correctly formatted code; runnpm run lint and npm run prettierbefore you open a PR. - TypeScript isstrict. Prefer narrow types to any / unknowncasts. - PHP code follows PSR-12;vendor/bin/phpunitand Composer's built-in scripts catch the rest. - Python code is formatted and linted with Ruff and type-checked withmypy in strict mode; run ruff check .,ruff format ., and mypy src in src/python/core/before you open a PR. - Rust code is formatted withrustfmtand linted with Clippy (warnings denied); runcargo fmtandcargo clippy --all-targets --all-features -- -D warnings in src/rust/core/before you open a PR. - Go code is formatted withgofmt and vetted with go vet; run gofmt -w .andgo vet ./... in src/go/core/before you open a PR. - Dart code is formatted withdart formatand analyzed withdart analyze --fatal-infos (lints from analysis_options.yaml); run both insrc/dart/core/ before you open a PR.

`Releasing (maintainers only)`

Only maintainers with write access can release new versions. This section is

documented here for completeness. Releases are triggered by Git tags. The version script updates every package in the workspace, creates a commit, and creates the tag: sh node scripts/version.mjs <version>
The version must be a valid semver value (e.g. 10.1.0or10.2.0-alpha.1). The script will:
1. Update version in every package.jsonacross the workspace 2. Update internal workspace dependency references 3. Updateversion in src/python/core/pyproject.toml,src/rust/core/Cargo.toml, and src/dart/core/pubspec.yaml(the Python, Rust, and Dart cores are not npm workspaces, so they are bumped explicitly to stay in lockstep) 4. Syncpackage-lock.json5. Create a Git commit and tag (e.g.v10.1.0)
Push the commit and the tag:
sh
git push && git push --tags
The tag triggers the Publish workflow, which:
1. Runs the test suite on Node 20, 22, 24, and 25 2. Builds every package 3. Picks the npm dist-tag: - Tags containingalpha, beta, or rc go out as next- Other tags on the default branch go out aslatest- Other tags on any other branch go out asv<major>-lts(so that backporting a patch to9.x after 10.xhas shipped does not overwritelatest) 4. Publishes all changed packages to npm viascripts/publish.mjs5. Buildssrc/python/core and publishes dicebear-coreto PyPI via trusted publishing (thepublish-pythonjob): no token and no separate repository, the same way the npm packages go out 6. Publishes the Rust coredicebear-coreto crates.io via trusted publishing (thepublish-rust job): likewise no token; cargo publishbuilds and uploadssrc/rust/corein one step 7. Publishes the Dart coredicebear_coreto pub.dev via automated publishing (thepublish-pub job): likewise no token; pub.dev verifies the v<version>tag against the pubspec version and publishessrc/dart/corestraight from the monorepo
The PHP port is the exception: Composer/Packagist consumes one Git repository per package rather than a monorepo subdirectory, sosplit-php-core.ymlmirrorssrc/php/core(tags included) to the standalonedicebear/dicebear-phprepository, and Packagist publishesdicebear/corefrom that mirror. All five ports ride the same version the monorepo tagged.
Licensing
By opening a pull request you agree that your contribution is released under the repository's MIT license. Avatar style artwork indicebear/stylesmay carry other licenses; see that repo'sLICENSE.md for details.
---
Package.Json (package.json)
{ "name": "root", "private": true, "packageManager": "[email protected]", "workspaces": { "packages": [ "src/js/*", "apps/*" ] }, "scripts": { "build": "turbo run build", "test": "turbo run test", "type-check": "turbo run type-check", "test:scripts": "node --test 'tests//*.test.js'", "fixtures:parity": "node tests/fixtures/parity/generate.mjs", "lint": "eslint . --cache", "lint:fix": "eslint . --cache --fix", "prettier": "prettier --write \"{src,apps}//.{js,ts,vue,json,md}\" \".md\"", "prettier:check": "prettier --check \"{src,apps}//.{js,ts,vue,json,md}\" \".md\"" }, "devDependencies": { "@eslint/js": "^10.0.1", "@stylistic/eslint-plugin": "^5.10.0", "@vue/eslint-config-typescript": "^14.6.0", "eslint": "^10.1.0", "eslint-config-prettier": "^10.1.8", "eslint-plugin-vue": "^10.7.0", "globals": "^17.4.0", "prettier": "^3.8.1", "turbo": "^2.5.0", "typescript": "^5.9.3", "typescript-eslint": "^8.58.0" }, "overrides": { "minimatch": ">=10.2.1", "serialize-javascript": "7.0.3", "esbuild": "^0.28.1" } }
---
Turbo.Json (turbo.json)
{ "$schema": "https://turbo.build/schema.json", "tasks": { "build": { "dependsOn": ["^build"], "outputs": ["lib/", ".vitepress/dist/", "dist/"] }, "test": { "dependsOn": ["build"], "cache": false }, "type-check": { "dependsOn": ["^build"] }, "dev": { "dependsOn": ["^build"], "persistent": true, "cache": false } } }
---
Apps/Docs/README (apps/docs/README.md)
dicebear.com
[](https://www.dicebear.com)
Contributing
See documentation: https://www.dicebear.com/guides/contribute-to-the-documentation
---
Apps/Docs/Package.Json (apps/docs/package.json)
{ "name": "@dicebear/docs", "engines": { "node": ">=20.19.0" }, "type": "module", "scripts": { "dev": "vitepress dev .", "build": "vitepress build .", "preview": "vitepress preview .", "type-check": "vue-tsc --noEmit" }, "dependencies": { "@dicebear/converter": "10.5.0", "@dicebear/core": "10.5.0", "@dicebear/styles": "^10.4.0", "@fontsource-variable/inter": "^5.2.8", "@lucide/vue": "^1.7.0", "@primeuix/themes": "^2.0.3", "@vueuse/core": "^14.2.0", "canvas-confetti": "^1.9.4", "change-case": "^5.4.4", "chart.js": "^4.5.1", "copy-to-clipboard": "^3.3.3", "highlight.js": "^11.11.1", "idb-keyval": "^6.2.2", "jszip": "^3.10.1", "pinia": "^3.0.4", "prando": "^6.0.1", "primevue": "^4.5.4", "random-int": "^3.1.0", "random-item": "^4.0.1", "simple-icons": "^16.7.0", "vitepress": "^2.0.0-alpha.19", "vue": "^3.5.17", "vue-chartjs": "^5.3.3" }, "devDependencies": { "@fontsource/inter": "^5.3.0", "@resvg/resvg-js": "^2.6.2", "@types/canvas-confetti": "^1.9.0", "@types/json-schema": "^7.0.15", "@types/node": "^24.0.3", "esbuild": "^0.28.1", "sharp": "^0.35.3", "typescript": "^5.9.3", "vue-tsc": "^3.2.4", "wawoff2": "^2.0.1", "yaml": "^2.9.0" }, "private": true }
---
Apps/Docs/Tsconfig.Json (apps/docs/tsconfig.json)
{ "compilerOptions": { "target": "esnext", "module": "esnext", "moduleResolution": "bundler", "allowImportingTsExtensions": true, "noEmit": true, "resolveJsonModule": true, "allowJs": true, "strict": true, "jsx": "preserve", "types": [], "paths": { "@theme/": ["./.vitepress/theme/"], "@playground/": ["./.vitepress/theme/components/playground/"] }, "skipLibCheck": true }, "include": ["env.d.ts", ".vitepress//*"], "exclude": [".vitepress/cache", ".vitepress/dist"] }
---
Apps/Docs/Turbo.Json (apps/docs/turbo.json)
{ "$schema": "https://turbo.build/schema.json", "extends": ["//"], "tasks": { "build": { "env": [ "VITE_PRIVACY_POLICY_URL", "VITE_COOKIE_POLICY_URL", "VITE_LEGAL_NOTICE_URL" ] } } }
---
Apps/Docs/Pages/Index (apps/docs/pages/index.md)
--- layout: page title: DiceBear | Open Source Avatar Library & API titleTemplate: false description: > DiceBear is a free, open source avatar library and avatar API with %STYLE_COUNT% styles. Create deterministic SVG profile pictures and placeholder avatars for user profiles, apps, and any project. Privacy-focused and self-hostable. aside: false ---
<script setup> import PageHome from '@theme/components/pages/PageHome.vue'; </script>
<PageHome />
---
Apps/Docs/Pages/Animated Avatars/Index (apps/docs/pages/animated-avatars/index.md)
--- layout: page title: Animated Avatars | Free Animated SVG Avatar Library & API titleTemplate: false description: > Create animated avatars with the DiceBear avatar library. %ANIMATED_STYLE_COUNT% styles animate with plain CSS inside the SVG, play in a normal img tag, and respect reduced motion settings. Free avatar API included. aside: false ---
<script setup> import PageAnimatedAvatars from '@theme/components/pages/PageAnimatedAvatars.vue'; </script>
<PageAnimatedAvatars />
---
Apps/Docs/Pages/Guides/Access All Available Options/Index (apps/docs/pages/guides/access-all-available-options/index.md)
--- title: Access All Available Style Options Programmatically description: > Learn how to programmatically access all available options of a DiceBear avatar style using the OptionsDescriptor class. ---
How to programmatically access all available options of an avatar style?
Each avatar style has different options depending on its components and colors. TheOptionsDescriptorclass lets you discover all available options at runtime.
JavaScript
js
import { Style, OptionsDescriptor } from '@dicebear/core'; import definition from '@dicebear/styles/micah.json' with { type: 'json' }; const style = new Style(definition); const descriptor = new OptionsDescriptor(style);console.log(descriptor.toJSON());
PHP
php
use Composer\InstalledVersions; use DiceBear\Style; use DiceBear\OptionsDescriptor; $basePath = InstalledVersions::getInstallPath('dicebear/styles'); $style = Style::fromJson(file_get_contents($basePath . '/src/micah.json')); $descriptor = new OptionsDescriptor($style);print_r($descriptor->toJSON());
Python
python
from importlib.resources import files from dicebear import OptionsDescriptor, Style style = Style.from_json( files("dicebear_styles").joinpath("micah.json").read_text("utf-8") ) descriptor = OptionsDescriptor(style)print(descriptor.to_json())
Go
go
import ( "fmt" dicebear "github.com/dicebear/dicebear-go/v10" "github.com/dicebear/styles/v10" ) style, _ := dicebear.NewStyle([]byte(styles.Micah)) descriptor := dicebear.NewOptionsDescriptor(style).ToJSON()fmt.Println(descriptor)
Dart
dart
import 'dart:convert'; import 'package:dicebear_core/dicebear_core.dart'; import 'package:dicebear_styles/micah.dart'; final style = Style.parse(micah); final descriptor = OptionsDescriptor(style);print(jsonEncode(descriptor.toJson()));
Field descriptor types
The toJSON()method returns a map of option names to field descriptors. Each descriptor has atype and additional properties depending on the type:
| Type | Properties | Example option | | --------- | ------------------------------------- | ------------------------ | |string | list? | seed, fontFamily| |number | min?, max?, list? | fontWeight| |boolean | | idRandomization| |enum | values, list?, weighted? | flip, *Variant| |color | list?, contrastTo?, notEqualTo? | *Color| |range | min?, max? | rotate, borderRadius |
- listindicates the option also accepts an array of values. -weighted(on enum fields) means the option additionally accepts aRecord<string, number>weight map for PRNG selection. -contrastTo(on color fields) names the color group the renderer will contrast against, so UIs can flag that this group's selection is contrast-driven rather than random. Only set when the style definition declares acontrastToconstraint on the group. -notEqualTo(on color fields) lists the color groups this group must differ from. A UI that picks colors itself has to apply the same rule, because a single explicit color per group leaves the renderer nothing to filter. Only set when the style definition declares anotEqualTo constraint on the group.
Component aliases (declared via extendsin the definition) do not contribute their own${alias}Variant / ${alias}Probabilityentries to the descriptor. They share their source component's user options.
---
Apps/Docs/Pages/Guides/Avatar Library Comparison/Index (apps/docs/pages/guides/avatar-library-comparison/index.md)
--- title: 'Avatar Library Comparison: DiceBear and the Alternatives' description: > Compare the DiceBear avatar library with Boring Avatars, Avvvatars, Multiavatar, and Jdenticon on styles, API, supported languages, and license. aside: false ---
<script setup> import DocsComparisonTable from '@theme/components/docs/DocsComparisonTable.vue'; </script>
Avatar library comparison
DiceBear is an open source avatar library with %STYLE_COUNT% styles, a free HTTP API, and libraries for six languages. Each style has a deep set of options: you can recolor the avatar, swap individual features, control the background, and weight how likely each variant is, so two avatars from the same style can look completely different. This page compares it with the avatar libraries developers most often weigh against it, to help you choose the right one for your project. All of them are good at what they do, and the best choice depends on your stack and the look you are after.
<DocsComparisonTable />
_This comparison is based on publicly available information and may not reflect the latest updates. Each tool has its own strengths, so choose what works best for your project._
DiceBear vs. Boring Avatars
Boring Avatars is a polished React component with a handful of clean, gradient-based styles. It installs in seconds and the gradients look great, which makes it a strong pick for a React app that wants that exact style. The hosted API is a separate, paid product.
DiceBear comes at it differently: more styles from different artists, no framework dependency, and a free HTTP API. As a Boring Avatars alternative DiceBear fits when you want a wider range of looks or you build outside React.
DiceBear vs. Avvvatars
Avvvatars is a small, tidy React component with two looks: an initials avatar and a geometric shape. It is light and quick to add, and when those two styles are all you need it does the job nicely.
DiceBear aims at a different spot, with many more styles, server-side rendering, and support beyond JavaScript.
DiceBear vs. Multiavatar
Multiavatar has real charm: one illustrated, multicultural character style, available in JavaScript, PHP, and Python. If that single look is what you want, it is a solid choice.
DiceBear covers the same languages and adds Rust, Go, and Dart, plus a larger set of styles and more output formats. It is the better fit for variety, while Multiavatar is the one to reach for when you love that specific character look.
DiceBear vs. Jdenticon
Jdenticon is a focused, dependency-free library that does geometric identicons really well. It runs in JavaScript, C#, and PHP, exports SVG and PNG, and is an excellent fit for .NET projects that just need identicons.
DiceBear also has an Identicon style if that is the look you want, along with many other styles and the HTTP API. When identicons are all you will ever need, Jdenticon is hard to beat, especially on .NET.
Which avatar library should you choose?
- Choose DiceBear for a range of art styles, deep customization, more than one language, several output formats, or self-hosting. - Choose Boring Avatars for its gradient styles in a React app. - Choose Avvvatars for a tiny two-style placeholder in React. - Choose Multiavatar for its illustrated multicultural character look. - Choose Jdenticon for geometric identicons, especially on .NET.
You can try any DiceBear style in the playground, or start with the JavaScript, PHP, Python, Rust, Go, or Dart library.
---
Apps/Docs/Pages/Guides/Contribute To The Api/Index (apps/docs/pages/guides/contribute-to-the-api/index.md)
--- title: Contribute to the HTTP API description: > Pointer to the contribution guide for the DiceBear HTTP API at api.dicebear.com. ---
Contribute to the API
The HTTP API at api.dicebear.com is a Fastify server that lives in its own repository:dicebear/api.
The contribution guide, including local setup, the test suite, the Docker-based production image, and the release process, lives alongside the code:
- CONTRIBUTING.mdindicebear/api
For hosting the API yourself (as opposed to working on its source), see Host the HTTP API yourself.
---
Apps/Docs/Pages/Guides/Contribute To The Documentation/Index (apps/docs/pages/guides/contribute-to-the-documentation/index.md)
--- title: Contribute to the Documentation description: > Pointer to the contribution guide for the DiceBear documentation site at dicebear.com. ---
Contribute to the documentation
This documentation site is a VitePress app underapps/docs/in the maindicebear/dicebearmonorepo. Every page has an "Edit this page on GitHub" link at the bottom that opens the corresponding source file.
Setup and workflow instructions live in the monorepo's contribution guide:
- Documentation changes section indicebear/dicebear/CONTRIBUTING.md
---
Apps/Docs/Pages/Guides/Contribute To The Editor/Index (apps/docs/pages/guides/contribute-to-the-editor/index.md)
--- title: Contribute to the Editor description: > Pointer to the contribution guide for the DiceBear editor at editor.dicebear.com. ---
Contribute to the editor
The editor at editor.dicebear.com is a Vue 3 + Vite + PrimeVue app. It lives underapps/editor/in the maindicebear/dicebear monorepo.
Setup and workflow instructions live in the monorepo's contribution guide:
- Editor changes section indicebear/dicebear/CONTRIBUTING.md
---
Apps/Docs/Pages/Guides/Contribute To The Library/Index (apps/docs/pages/guides/contribute-to-the-library/index.md)
--- title: Contribute to the Library description: > Learn how to contribute an avatar style, improve an existing one, or work on the DiceBear core packages. ---
Contribute to the library
DiceBear is maintained across several repositories on GitHub. Each repo has its ownCONTRIBUTING.mdwith setup, scripts, testing, and release instructions. Pick the one that matches what you want to work on.
Avatar styles
New avatar styles and fixes to existing styles live indicebear/styles. Most styles are authored in Figma and exported with the DiceBear Exporter plugin, so the workflow there is not the usual "edit a JSON file" loop.
- CONTRIBUTING.mdindicebear/styles
Core library, CLI, documentation, editor
The JavaScript, PHP, Python, Rust, Go and Dart cores, the CLI, the VitePress documentation (including the Playground), and the standalone editor all live in the maindicebear/dicebearmonorepo. See:
- CONTRIBUTING.mdindicebear/dicebear
It covers the monorepo layout, per-package workflow, cross-language parity tests across the JavaScript, PHP, Python, Rust, Go and Dart cores, and the release process.
JSON Schema
The schema for avatar style definitions and runtime options is versioned separately indicebear/schema.
- CONTRIBUTING.mdindicebear/schema
Figma exporter plugin
The Figma plugin that produces new avatar style definitions lives indicebear/exporter-plugin-for-figma.
- CONTRIBUTING.mdindicebear/exporter-plugin-for-figma
---
Apps/Docs/Pages/Guides/Core Options/Index (apps/docs/pages/guides/core-options/index.md)
--- title: Core Options description: > The options every DiceBear core understands, shared across the JavaScript, PHP, Python, Rust, Go, and Dart libraries and the HTTP API: seed, flip, rotate, scale, size, background, and the per-component and per-color options. ---
Core options
These options are the same across every DiceBear core: the JavaScript, PHP, Python, Rust, Go, and Dart libraries, and the HTTP API. Only the way you pass them differs from one language to the next, so each library page shows that in its own syntax. The names, types, defaults, and behavior below do not change.
They apply to every avatar style. Where the type lists [min, max], you may pass either a fixed value or a two-element tuple. The PRNG samples a value from the tuple's range.
| Option | Type | Default | Description | | ----------------- | ------------------------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | |seed | string | ''| Seed for deterministic generation | |flip | 'none' \| 'horizontal' \| 'vertical' \| 'both' | 'none'| Flip the avatar (accepts an array of values to randomize) | |rotate | number \| [min, max] | 0| Rotation in degrees (−360 to 360) | |scale | number \| [min, max] | 1 | Uniform scale factor around the canvas center (0 to 10; 1is original size) | |borderRadius | number \| [min, max] | 0 | Border radius in percent of the canvas (0 to 50; 50makes a circle) | |size | integer| _unset_ | Output size in pixels (1 to 4096); when unset the SVG scales to its container | |translateX | number \| [min, max] | 0| Horizontal translation in percent of the canvas width (−1000 to 1000) | |translateY | number \| [min, max] | 0| Vertical translation in percent of the canvas height (−1000 to 1000) | |idRandomization | boolean | false | Suffix every SVG id with a random, non-deterministic value (avoids url(#…)collisions when several avatars share a page) | |title | string | _unset_ | Accessible title; when set, the SVG becomes role="img" with <title>| |fontFamily | string \| string[] | 'system-ui'| Font family for text-based styles (CSS-style font stack, no quotes) | |fontWeight | integer \| integer[] | 400| Font weight for text-based styles (1 to 1000) | |tags | string \| string[] | _unset_ | Keep only variants matching these tags (category or category:value, prefix with ! to disallow) |
Background options
These options are available for every style, even ones that don't declare abackground color group in their definition.
| Option | Type | Default | Description | | -------------------------- | --------------------------------- | ---------- | ------------------------------------------------------------------ | |backgroundColor | string \| string[] | _unset_ | Background colors as hex (# optional, #RGB to #RRGGBBAA) | |backgroundColorFill | 'solid' \| 'linear' \| 'radial' | 'solid'| Background fill type (accepts an array of values to randomize) | |backgroundColorFillStops | integer \| [min, max] | 2 | Number of gradient stops (minimum 2); ignored when fill is solid| |backgroundColorAngle | number \| [min, max] | 0| Gradient angle in degrees (−360 to 360) | |backgroundColorOrder | 'random' \| 'fixed' | 'random' | Use the given colors in order (fixed) instead of shuffling them |
Dynamic component options
For each component in a style (e.g. eyes, mouth, hair), the following options are available:
| Pattern | Type | Description | | ------------------------ | ------------------------------------------- | ------------------------------------------------------ | |{component}Variant | string \| string[] \| { variant: weight }| Restrict to specific variants, optionally with weights | |{component}Probability | number | Visibility probability in percent (0 to 100) |
A component's rotation, translation, and scale are sampled at render time from the component definition and are not user options: there are no{component}Rotate, {component}TranslateX, {component}TranslateY, or{component}Scale options.
Component aliases (declared via extendsin the style definition) do not expose their own option keys. They share{source}Variant and {source}Probabilitywith the component they extend.
Dynamic color options
For each color group in a style (e.g. skin, hair) and background, the following options are available:
| Pattern | Type | Description | | ----------------------- | --------------------------------- | ------------------------------------------------------------------ | |{color}Color | string \| string[] | Override the palette with hex values (#optional) | |{color}ColorFill | 'solid' \| 'linear' \| 'radial'| Fill type (accepts an array of values to randomize) | |{color}ColorFillStops | integer \| [min, max] | Number of gradient stops (minimum 2); ignored when fill is solid| |{color}ColorAngle | number \| [min, max]| Gradient angle in degrees (−360 to 360) | |{color}ColorOrder | 'random' \| 'fixed' | Use the given colors in order (fixed) instead of shuffling them |
With {color}ColorOrder: 'fixed', colors passed via {color}Colorkeep exactly the order you give them: gradient fills apply them as stops from first to last, solid fills always use the first color, and the number of gradient stops defaults to the number of given colors. Without{color}Color, fixedonly skips the shuffle; the style's palette is deduplicated and used in sorted order. Constraints in the style definition (contrastTo, notEqualTo) still apply, so the result can stay seed-dependent through the referenced color groups.
Variant tags
When a style tags its variants, the tagsoption filters the variant pool to the traits you want, across every component at once. A tag iscategoryorcategory:value, such as animation or hairLength:long. Within one category the values combine with "or", different categories combine with "and", a bare category requires the trait, and a leading!disallows. See Filter variants with tags for the full rules and the categories DiceBear's styles use.
---
Apps/Docs/Pages/Guides/Create An Avatar Style From Scratch/Index (apps/docs/pages/guides/create-an-avatar-style-from-scratch/index.md)
--- title: Create an Avatar Style from Scratch description: > Learn how to create a DiceBear avatar style from scratch by writing a JSON definition file. No Figma or design tools required. ---
Create an avatar style from scratch
We highly recommend our Figma plugin to create an avatar style. Most of DiceBear's official avatar styles were created with the plugin. But you can also create an avatar style by writing a JSON definition file by hand.
Minimal example
A minimal style definition with a colored circle:
json
{ "canvas": { "width": 100, "height": 100, "elements": [ { "type": "element", "name": "circle", "attributes": { "cx": "50", "cy": "50", "r": "45", "fill": { "type": "color", "name": "background" } } } ] }, "colors": { "background": { "values": ["#f94144", "#f9c74f", "#90be6d", "#43aa8b", "#577590"] } } }
Save this as my-style.json and test it:
text
dicebear ./my-style.json ./output --count 5
The PRNG picks a different background color for each seed.
Adding components
Components are the randomizable parts of your avatar. Each component has multiple variants that the PRNG can choose from.
Let's add a face component with two variants:
text
/ Detailed source-code truncated for AI context efficiency. /
The canvas.elements array references the facecomponent via{ "type": "component", "name": "face" }. The PRNG selects either the smileorneutral variant.
Multiple components
You can add as many components as you like. Each component is independent: the PRNG selects a variant for each one separately.
json
{ "components": { "eyes": { "width": 100, "height": 100, "variants": { "round": { "elements": [...] }, "narrow": { "elements": [...] } } }, "mouth": { "width": 100, "height": 100, "variants": { "smile": { "elements": [...] }, "open": { "elements": [...] }, "flat": { "elements": [...] } } }, "accessories": { "width": 100, "height": 100, "probability": 30, "variants": { "glasses": { "elements": [...] }, "hat": { "elements": [...] } } } } }
Probability
The probabilityproperty (0-100) controls how often a component appears. In the example above,accessoriesonly appears in ~30% of generated avatars. Default is100 (always visible).
Variant weights
Control how often specific variants are selected:
json
{ "variants": { "common": { "weight": 3, "elements": [...] }, "uncommon": { "weight": 1, "elements": [...] }, "rare": { "weight": 0, "elements": [...] } } }
Higher weight = more likely to be selected. Weight 0is only chosen when all other weights are also0. Default weight is 1.
Component transforms
Components can have default rotation, translation, and scale ranges that the PRNG samples per render. All four fields use the same{ min, max, step? }range object. See Ranges for the full reference.
json
{ "eyes": { "width": 80, "height": 40, "rotate": { "min": -5, "max": 5 }, "scale": { "min": 0.95, "max": 1.05 }, "translate": { "x": { "min": -2, "max": 2 }, "y": { "min": -3, "max": 3 } }, "variants": { ... } } }
Set min === max for a fixed value, or add "step": <n>to quantize the range to discrete buckets.
Color palettes
Colors can be referenced from element attributes. The PRNG picks a value from the palette for each avatar.
json
{ "colors": { "skin": { "values": ["#f5d6c3", "#d4a889", "#a67c5b", "#614335"] }, "hair": { "values": ["#2c1b18", "#b58143", "#d6b370", "#724133"], "notEqualTo": ["skin"] }, "text": { "values": ["#ffffff", "#000000"], "contrastTo": "background" } } }
Color references
Use color references in SVG attributes to apply dynamic colors:
json
{ "type": "element", "name": "circle", "attributes": { "fill": { "type": "color", "name": "skin" } } }
Color constraints
notEqualToprevents two color groups from selecting the same color. In the example above,hair will never be the same color as skin.
contrastTopicks the color with the highest contrast ratio against the referenced color group. This is useful for ensuring text is readable against a background.
Metadata
Add metadata to your definition for license attribution:
json
{ "meta": { "license": { "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/", "text": "Full license text..." }, "creator": { "name": "Your Name", "url": "https://your-website.com" }, "source": { "name": "My Style", "url": "https://github.com/your/repo" } } }
This metadata appears in:
- The <metadata>RDF block inside generated SVGs (Dublin Core terms; see the Core implementation spec) - The CLI license banner - The documentation (if your style is added to the official collection)
Schema validation
Add the $schema property to enable validation in your editor:
json
{ "$schema": "https://cdn.hopjs.net/npm/@dicebear/[email protected]/dist/definition.min.json", "canvas": { ... } }
Most editors (VS Code, WebStorm, etc.) will provide autocompletion and inline validation for your definition file.
Testing
With the CLI
text
dicebear ./my-style.json ./output --count 10 dicebear ./my-style.json ./output --seed "Alice" --format png
With the JS Library
js
import { Style, Avatar } from '@dicebear/core'; import definition from './my-style.json' with { type: 'json' };const style = new Style(definition); const avatar = new Avatar(style, { seed: 'test' }); console.log(avatar.toString());
With the PHP Library
php
use DiceBear\Avatar; use DiceBear\Style;$style = Style::fromJson(file_get_contents('./my-style.json')); $avatar = new Avatar($style, ['seed' => 'test']); echo (string) $avatar;
With the Python Library
python
from pathlib import Path from dicebear import Avatar, Stylestyle = Style.from_json(Path("./my-style.json").read_text("utf-8")) avatar = Avatar(style, {"seed": "test"}) print(avatar.to_string())
With the Rust Library
rust
use dicebear_core::{Avatar, Style}; use serde_json::json; use std::fs; let definition = fs::read_to_string("./my-style.json")?; let style = Style::from_str(&definition)?;let avatar = Avatar::new(&style, json!({ "seed": "test" }))?; println!("{}", avatar.to_svg());
With the Go Library
go
import ( "fmt" "os" dicebear "github.com/dicebear/dicebear-go/v10" ) definition, _ := os.ReadFile("./my-style.json") style, _ := dicebear.NewStyle(definition)avatar, _ := dicebear.NewAvatar(style, map[string]any{"seed": "test"}) fmt.Println(avatar.SVG())
With the Dart Library
dart
import 'dart:io'; import 'package:dicebear_core/dicebear_core.dart'; final style = Style.parse(File('./my-style.json').readAsStringSync());final avatar = Avatar(style, {'seed': 'test'}); print(avatar.svg);
Next steps
- See the Definition Schema Reference for the complete specification - Browse the official definitions for real-world examples - Use the Figma plugin for a visual workflow
---
Apps/Docs/Pages/Guides/Create An Avatar Style With Figma/Index (apps/docs/pages/guides/create-an-avatar-style-with-figma/index.md)
--- title: Create an Avatar Style with Figma description: > Step-by-step guide to creating a custom DiceBear avatar style using the DiceBear Figma Exporter plugin. ---
Create an avatar style with Figma
Our Figma plugin is the easiest way to create an avatar style for DiceBear. The following tutorial requires basic knowledge about Figma.
Step 1
If you want DiceBear to dynamically change colors in your avatar, you have to create the colors in Figma as locale style. Arrange the colors in groups. Name them according to the following pattern:<group>/<option-name>. For example,skin/light.
You will use the locale styles later to colorize paths. DiceBear will then change the colors of the paths within a group depending on the seed and color settings. For the names of<group> and <option-name>you can use alphanumeric characters as well as hyphens.
In the following example you can see how this could look like:
<video src="/guides/create-an-avatar-style-with-figma/1.mp4" controls muted></video>
Step 2
Now assign a color from the created groups to your paths that will be colored dynamically. Which color from a group does not matter. The important thing is that the group is correct.
<video src="/guides/create-an-avatar-style-with-figma/2.mp4" controls muted></video>
Step 3
Create the individual parts of your avatar as components. Again, use the<group>/<option-name> naming pattern to create groups.
Identical to the colors, DiceBear will later (taking into account the seed and the settings) select a component from a group and put it into the avatar.
<video src="/guides/create-an-avatar-style-with-figma/3.mp4" controls muted></video>
Step 4
Make sure that each component in a group has the same dimensions.
<video src="/guides/create-an-avatar-style-with-figma/4.mp4" controls muted></video>
Step 5
Create as many color and component groups as you like. Then you can bring all the components together.
To do this, create a frame and make sure that the width and height are identical. From the Assets tab, drag one instance from each component group into the frame.
<video src="/guides/create-an-avatar-style-with-figma/5.mp4" controls muted></video>
Step 6
Search now for the DiceBear Exporter plugin. Make sure you have selected the frame and start the plugin.
A dialog will open where you can make all kinds of settings. For example the name of your avatar style, the license or the probability with which the components will appear in your avatar later.
The settings are automatically saved to your frame. Once you are happy with your settings, you can export your avatar style.
<video src="/guides/create-an-avatar-style-with-figma/6.mp4" controls muted></video>
::: tip
Make sure you select version 10.x in the export settings. This guide covers version 10.x.
:::
Step 7
The plugin exports a JSON file: your style definition. This file is ready to use immediately, without a build step.
You can test your style right away with the CLI:
text
dicebear ./your-style.json ./test-output --count 10
This generates 10 sample avatars in the ./test-output directory.
Step 8
Congratulations! You can now use your avatar style with the JS Library, the PHP Library, the Python Library, the Rust Library, the Go Library, the Dart Library, or the CLI.
With the JS Library
js
import { Style, Avatar } from '@dicebear/core'; import definition from './your-style.json' with { type: 'json' };const style = new Style(definition); const avatar = new Avatar(style, { seed: 'dicebear', // ... other options });
With the PHP Library
php
use DiceBear\Avatar; use DiceBear\Style; $style = Style::fromJson(file_get_contents('./your-style.json'));$avatar = new Avatar($style, [ 'seed' => 'dicebear', // ... other options ]);
With the Python Library
python
from pathlib import Path from dicebear import Avatar, Style style = Style.from_json(Path("./your-style.json").read_text("utf-8"))avatar = Avatar(style, { "seed": "dicebear", # ... other options })
With the Rust Library
rust
use dicebear_core::{Avatar, Style}; use serde_json::json; use std::fs; let definition = fs::read_to_string("./your-style.json")?; let style = Style::from_str(&definition)?;let avatar = Avatar::new(&style, json!({ "seed": "dicebear", // ... other options }))?;
With the Go Library
go
import ( "os" dicebear "github.com/dicebear/dicebear-go/v10" ) definition, _ := os.ReadFile("./your-style.json") style, _ := dicebear.NewStyle(definition)avatar, _ := dicebear.NewAvatar(style, map[string]any{ "seed": "dicebear", // ... other options })
With the Dart Library
dart
import 'dart:io'; import 'package:dicebear_core/dicebear_core.dart'; final style = Style.parse(File('./your-style.json').readAsStringSync());final avatar = Avatar(style, { 'seed': 'dicebear', // ... other options });
With the CLI
text
dicebear ./your-style.json ./avatars --seed "dicebear" --format png
::: tip
The CLI automatically detects all available options from your style definition. Use--help with your definition file to see them:
text
dicebear ./your-style.json --help
:::
---
Apps/Docs/Pages/Guides/Dicebear For Ai Assistants/Index (apps/docs/pages/guides/dicebear-for-ai-assistants/index.md)
--- title: DiceBear for AI Assistants and LLMs description: > Make coding assistants write current DiceBear code: a rules block for your project, llms.txt, a Markdown version of every page, and JSON option descriptors for every avatar style. ---
DiceBear for AI assistants
Coding assistants write DiceBear from memory, and that memory mostly predates version 10. The block below is the fix: paste it into your project and the assistant has the current package for your language, the shape of the API, and the address to look options up at.
Rules for your project
Assistants read a rules file from the repository they work in, usuallyAGENTS.md. Everything an assistant needs is in this one block:
text
/ Detailed source-code truncated for AI context efficiency. /
If your assistant can fetch URLs, one sentence covers most of what the block says:
Read https://www.dicebear.com/llms.txt before you write DiceBear code.
Six libraries, identical output
DiceBear is not a JavaScript library with wrappers around it. Six native cores are held to byte-identical output, so the same style, seed and options produce the same SVG in each. Only the syntax for passing the options differs.
| Library | Packages | Since | | ------------------------------------- | ------------------------------------------------------- | ------ | | JavaScript |@dicebear/core, @dicebear/styles| 10.0.0 | | PHP |dicebear/core, dicebear/styles| 10.0.0 | | Python |dicebear-core, dicebear-styles| 10.1.0 | | Rust |dicebear-core, dicebear-styles| 10.2.0 | | Go |github.com/dicebear/dicebear-go/v10, .../styles/v10| 10.2.0 | | Dart |dicebear_core, dicebear_styles | 10.3.0 |
Five of the six shipped during 2026, which puts them outside most training data. That is why the block above names them explicitly: without it, an assistant will tell you there is no DiceBear library for your language and hand you JavaScript.
Each style page carries the loading snippet for all six languages, so one page covers whichever you are working in.
Machine-readable sources
| Address | Contents | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ | |https://www.dicebear.com/llms.txt| Index of the documentation, current package versions, and every avatar style | |https://www.dicebear.com/llms-full.txt| Every page in one file: guides first, then all styles with their option tables (about half a megabyte) | | Any page URL plusindex.md | That single page as Markdown |
The Markdown version of a page sits next to its HTML, so appending index.mdto the address is enough:
text
https://www.dicebear.com/how-to-use/http-api/index.md
Each page also carries a copy button in its header that puts the same text on your clipboard, which saves a round trip when you want to paste one page into a chat window.
Option names are what assistants invent most often, and the API answers that question directly, without a page to parse:
text
https://api.dicebear.com/10.x https://api.dicebear.com/10.x/<styleName>/options.json https://api.dicebear.com/10.x/<styleName>/definition.json
The version root lists the available style names.options.jsondescribes every option a style takes, including its type, its range, and the exact enum values. The same table is printed on each style page.
Why the old calls need spelling out
::: details How an outdated call passes for a working one
The HTTP API drops a query parameter it does not recognize. radius=50returns a square avatar,eyes=variant01returns whatever eyes the seed picked, and neither reports a problem. Versions5.x through 9.xare still served, so a URL built for the old API keeps working.@dicebear/collectionis still on npm at its last 9.x release, so that install succeeds as well.
The one exception is the retired avatars.dicebear.comhost, which answers410 Gone.
Nothing here is a defect you need to work around. Old versions stay available on purpose, and dropping unknown parameters is what keeps a URL from breaking when a style changes. The combination is only a problem when the code was written from memory rather than from the current docs, which is why the block above lists the pairs explicitly.
:::
::: details What changed in 10.0.0
Every option named after a component gained a Variant suffix, so eyesbecameeyesVariant. The avatar styles moved out of individual packages and into@dicebear/styles as JSON definitions, and createAvatar()was replaced by theStyle and Avatarclasses. The changelog has the full list, and the JavaScript library page documents the current classes.
:::
Crawling and training
The robots.txt allows assistants and their crawlers; only the site notice is excluded. The documentation is MIT licensed; the avatar styles are not, and each one carries its own license.
---
Apps/Docs/Pages/Guides/Filter Variants With Tags/Index (apps/docs/pages/guides/filter-variants-with-tags/index.md)
--- title: Filter Avatar Variants with Tags description: > Variant tags describe how a variant looks or behaves. The tags option filters the variant pool. Today that turns on the opt-in animation of the animated styles, and an upcoming release adds traits like mood and hair length. ---
Filter avatar variants with tags
Avatar styles can describe their variants with tags. A tag is a short label likeanimation or hairLength:longthat says something about a variant. Tags only describe, they never change the artwork. They let you narrow the pool of variants an avatar is drawn from, and they work the same way across every style that carries them.
Filter with the tags option
tagsis a core option, so it works everywhere the avatar is generated. Pass the tags you want to keep:
js
import { Style, Avatar } from '@dicebear/core'; import planets from '@dicebear/styles/planets.json' with { type: 'json' };const style = new Style(planets); const avatar = new Avatar(style, { seed: 'John', tags: ['animation'], });
In the HTTP API the same filter is a comma-separated query parameter:
text
https://api.dicebear.com/10.x/planets/svg?seed=John&tags=animation
How the filter works
A tag token is category or category:value, optionally prefixed with !. Each token narrows a component's pool of variants:
| Token | Effect | | ----------------- | -------------------------------------------------------------------------------------------------------------------------- | |category:value| Keeps variants that carry this tag, plus variants with no tag in the category. Several values of one category act as "or". | |category| Requires the category: drops variants that carry no tag in it. It binds only in components that use the category at all. | |!category:value| Drops every variant that carries exactly this tag. | |!category | Drops every variant that carries any tag in the category. |
A few rules tie the tokens together:
- A category only touches the components that use it, so you change one trait and the rest of the avatar stays varied. - Different categories act as "and", and a disallow (!) always wins over an allow. - A per-component variant option is more specific and takes precedence. When you setanimationVariant directly, the tagsfilter is ignored for the animation and applies only to the other components. - Only an unknown category is ignored. An unknown value is not. Because no variant matches it, every variant tagged in that category drops out. A typo inhairLenght:long changes nothing, while a typo in hairLength:lngremoves the hair.
::: tip
If a filter leaves a component with no matching variants, that component is not drawn. Loosen the filter or check the tags the style actually provides on its style page. Passingtagsto a style that carries no tags does nothing.
:::
The tags DiceBear offers
::: warning Only the animation tag ships today
The character categories are not set on any style yet. A filter likemood:positive or hairLength:long has no effect for now.
:::
Right now, DiceBear's own styles carry tags in one place: the opt-in animation of the animated styles. An upcoming release adds a shared set for the character styles with mood, hair length, headwear, facial hair, eyewear, and accessory. Those definitions already live in How DiceBear tags variants.
| Category | Values | Found on | | ----------- | -------------------------- | ------------------------------------------ | |animation | (bare category, no values) | the animation component of animated styles |
The animation is off by default, and the filter controls it like this:
| tags| Result | | ------------ | --------------------------------------------------- | |animation| Turns the animation on, at a random speed per seed. | |!animation | Keeps the avatar static, which is also the default. |
For a fixed speed, skip the filter and set the variant directly with theanimationVariant option (e.g. animationVariant: 'slow'), which is more specific and always wins.
js
// Turn on the opt-in animation of an animated style, at a random speed // per seed. const avatar = new Avatar(style, { seed: 'Alex', tags: ['animation'], });
Custom styles
Tags are not limited to this list. A custom style can reuse these categories, add its own values, or define entirely different ones. The only rule is the grammar: a tag iscategory or category:value, and each segment is camelCase (for examplemouthExpression:smug or species:robot). There is no fixed vocabulary a style has to follow, so pick the categories that describe your artwork.
---
Apps/Docs/Pages/Guides/Host The Http Api Yourself/Index (apps/docs/pages/guides/host-the-http-api-yourself/index.md)
--- title: Self-Hosted Avatar API – Host DiceBear Yourself description: > Self-host the DiceBear avatar API for privacy-by-design and commercial use. Docker and Node.js deployment options available. ---
Self-hosted avatar API: host DiceBear yourself
You can host the HTTP API yourself. This is not necessary for most users, but it can be useful in some cases.
You can find the source code for the HTTP API on GitHub. The code is written in TypeScript and uses the Fastify framework.
With Docker
The easiest way to host the HTTP API yourself is to use the docker image. You can find the image on Docker Hub.
text
docker run --tmpfs /run --tmpfs /tmp -p 3000:3000 -i -t dicebear/api:4
Or you can use docker-compose.ymlto configure the HTTP API and start it with "docker compose up".
text
services: dicebear: image: dicebear/api:4 restart: always ports: - '3000:3000' tmpfs: - '/run' - '/tmp'
Without Docker
If you don't want to use docker, you can also run the HTTP API directly on your machine. You need to have Node.js installed.
text
git clone [email protected]:dicebear/api.git cd apinpm install npm run build npm start
Optional style metadata endpoints
Besides the avatar endpoints, your instance can expose two metadata endpoints per style. Both are disabled by default and can be enabled individually with an environment variable:
text
http://localhost:3000/10.x/<styleName>/definition.json http://localhost:3000/10.x/<styleName>/options.json
- definition.jsonreturns the raw style definition, the same JSON that is shipped with the style package. Enable it withDEFINITION=1. -options.jsonreturns a descriptor of all options the style accepts: field types, allowed enum values, and value ranges. Options listed inEXCLUDED_OPTIONSare omitted, so the response always matches what your instance actually accepts. Enable it withOPTIONS=1.
Both responses are cached according to CACHE_CONTROL_STYLES.
Environment variables
The HTTP API supports the following environment variables:
| Variable | Default | Description | | ---------------------------------- | --------------------------------------------- | -------------------------------------------------------------------- | |PORT | 3000| Port to listen on. | |HOST | 0.0.0.0| Host to bind to (all IPv4 addresses by default). | |LOGGER | 0| Enable request logger (1 = on, 0 = off). | |WORKERS | 1| Number of Node.js worker threads. | |VERSIONS | 10| Comma-separated list of supported DiceBear major versions. | |CACHE_CONTROL_AVATARS | 31536000| Cache duration for avatar responses in seconds (1 year). | |CACHE_CONTROL_STYLES | 3600| Cache duration for the styles listing in seconds (1 hour). | |PNG | 1| Enable the PNG endpoint (1 = on, 0 = off). | |PNG_SIZE_MIN | 1| Minimum allowed PNG size in px. | |PNG_SIZE_MAX | 256| Maximum allowed PNG size in px. | |PNG_SIZE_DEFAULT | 128| Default PNG size in px. | |PNG_EXIF | 1| Enable EXIF metadata for PNG (1 = on, 0 = off). | |JPEG | 1| Enable the JPEG endpoint (1 = on, 0 = off). | |JPEG_SIZE_MIN | 1| Minimum allowed JPEG size in px. | |JPEG_SIZE_MAX | 256| Maximum allowed JPEG size in px. | |JPEG_SIZE_DEFAULT | 128| Default JPEG size in px. | |JPEG_EXIF | 1| Enable EXIF metadata for JPEG (1 = on, 0 = off). | |WEBP | 1| Enable the WebP endpoint (1 = on, 0 = off). | |WEBP_SIZE_MIN | 1| Minimum allowed WebP size in px. | |WEBP_SIZE_MAX | 256| Maximum allowed WebP size in px. | |WEBP_SIZE_DEFAULT | 128| Default WebP size in px. | |WEBP_EXIF | 1| Enable EXIF metadata for WebP (1 = on, 0 = off). | |AVIF | 1| Enable the AVIF endpoint (1 = on, 0 = off). | |AVIF_SIZE_MIN | 1| Minimum allowed AVIF size in px. | |AVIF_SIZE_MAX | 256| Maximum allowed AVIF size in px. | |AVIF_SIZE_DEFAULT | 128| Default AVIF size in px. | |AVIF_EXIF | 1| Enable EXIF metadata for AVIF (1 = on, 0 = off). | |JSON | 1| Enable the JSON endpoint (1 = on, 0 = off). | |DEFINITION | 0 | Enable the per-style definition.jsonendpoint (1 = on, 0 = off). | |OPTIONS | 0 | Enable the per-style options.jsonendpoint (1 = on, 0 = off). | |INITIALS_FILTER | 1 | Replace blocked text in rendered avatars with *(1 = on, 0 = off). | |QUERY_STRING_ARRAY_LIMIT_MIN | 20| Minimum number of values allowed per array parameter. | |EXCLUDED_OPTIONS | idRandomization,fontFamily,fontWeight,title| Comma-separated list of option names to exclude. | |QUERY_STRING_PARAMETER_LIMIT_MIN | 100 | Minimum number of query string parameters allowed. |
---
Apps/Docs/Pages/Guides/How Dicebear Tags Variants/Index (apps/docs/pages/guides/how-dicebear-tags-variants/index.md)
--- title: How DiceBear Tags Variants description: > How DiceBear assigns variant tags to its own styles: the animation tags that ship today, and the planned standard set for the character styles covering mood, hair length, headwear, facial hair, eyewear, and accessory. ---
How DiceBear tags variants
DiceBear's own styles share one set of tags, so thetagsfilter behaves the same from one style to the next. Today only one category ships: theanimationtag of the animated styles. The character categories further down arrive with an upcoming release.
DiceBear tags each variant by looking at how it renders, not at its name. Names are not always reliable. A hair variant calledlong04can turn out short once you look at it, so the rendered shape decides the tag.
A few principles keep the tags consistent:
- Tags only describe. A variant carries the labels that fit what it shows, and never a category outside the set below. - A tag is added only when the trait is clear. An ambiguous or purely decorative variant is left untagged rather than guessed. Where a category has a bare form, asheadweardoes, the bare tag is still set and only the value is left off. - Most variants carry no tag or one tag. A few carry two, such as hair with a visible hat. - Variant tags only add information, they never remove a variant on their own. To leave something out at render time, use the!form of thetags option. Disallowing lives in the filter, not in the data.
The tag grammar is category or category:value, each segment camelCase and alphanumeric. A variant holds at most 32 tags.
Animation
The animationcategory covers the animation component of animated styles. It is a bare category without values: every animated variant carries the plainanimationtag, and the static default variant carries no tag, so the animation stays off until you ask for it.
- ['animation']turns the animation on, at a random speed per seed. -['!animation']keeps the avatar static. A disallow wins, so it also overrides ananimation in the same list.
The speed steps are variants, not traits, so they carry no value tags. To pin a speed, set theanimationVariant option (e.g. animationVariant: 'slow'), which is more specific than the filter and always wins.
Planned categories
::: warning Not shipped yet
No DiceBear style carries the categories below, so filtering on them has no effect for now.
:::
The categories below are the standard set for the character styles. We publish the definitions ahead of time so custom styles can reuse them and stay compatible with the filter examples in the docs.
Mood
The moodcategory covers the parts of the face that carry expression: the mouth, eyes, eyebrows, and any combined expression component. It has two values, and a variant gets at most one.
- negativefor a clearly unfriendly or distressed expression: angry, sad, or scared. -positivefor everything else, including happy, neutral, surprised, playful, and confused faces.
Only a clear negative is tagged negative. Anything friendly, neutral, or ambiguous ispositive, so filtering on mood:positivealways leaves a usable variant and never empties a component. The usual reason to filter mood is to keep avatars friendly, andmood:positive does that.
Mood is deliberately coarse. A finer list of feelings would not survive filtering, because a specific feeling like "sad" often has no matching variant for every part of a face, so that part would drop out and the avatar would render incomplete. Two values keep every filtered face complete.
A part with no expression at all, such as a face mask or a purely graphic shape, is left without a mood.
Hair length
The hairLengthcategory covers hair components. It is optional and only set when the length is actually visible.
- baldfor no hair, or hair shaved to the scalp. -shortfor hair above the ears, cropped or buzzed. -mediumfor around ear-to-jaw length. -long for hair past the jaw, shoulder length or longer.
When the hair is gathered or pinned up so the length cannot be read, such as a bun or a top-knot, the length is left off. A ponytail or pigtails with a visible hanging tail still gets a length. A variant that is really headwear gets aheadwear tag, and a variant showing both hair and a hat may carry both.
The cut and the texture of the hair carry no tags. Whether hair reads as wavy or curly is a judgment call that would come out differently from one style to the next, and the filter is there to steer the look in broad strokes, not to pick a haircut. For a specific hairstyle, set the style's own hair variant option.
Headwear
The headwearcategory covers anything worn on the head. Every such variant carries at least the bareheadwear tag, so !headwearremoves all of them. A value comes on top of it when the shape is unmistakable:
- hatfor a crown with a brim all the way around, such as a sun hat or a fedora. -capfor a brim at the front only, such as a baseball or a flat cap. -beaniefor a soft, close-fitting hat without a brim. -turbanfor wrapped cloth that covers the hair and leaves the neck free. -headscarffor wrapped cloth that covers the hair together with the neck or the shoulders. -headband for a band alone, with the hair still visible.
The values name the shape of the garment, not the person wearing it. That is why the two wrapped forms are told apart by the neck, and why the tag saysheadscarfrather than naming a particular garment: the drawing shows cloth, and the same cloth means different things to different people.
Facial hair
The facialHaircategory covers beards, mustaches, and sideburns. Likeanimationit is a bare category without values: a variant showing any facial hair carries the plainfacialHair tag, and a clean-shaven one carries none.
- ['!facialHair']leaves facial hair out. -['facialHair']drops the untagged variants of the components that use the category. Whether such a component is drawn at all is still up to its probability.
Where stubble ends and a beard begins is a call that would land differently from one style to the next, and what the filter is good for is saying yes or no to facial hair. For a specific beard, set the style's facial hair variant option.
Eyewear
The eyewear category covers glasses.
- glassesfor clear lenses or spectacles. -sunglasses for filled or dark lenses.
Accessory
The accessory category covers worn extras.
- earringsfor ear jewelry. -maskfor a face covering worn over the mouth or face, such as a medical mask. A mask is a worn item, not an expression, so a masked mouth getsaccessory:mask and no mood.
Custom styles
This set is what DiceBear's own styles use, not a rule every style has to follow. A custom style can reuse these categories, add its own values, or define entirely different ones. As long as the grammar holds, you are free to describe your artwork in whatever way fits it best.
---
Apps/Docs/Pages/Guides/How Do I Set A Gender/Index (apps/docs/pages/guides/how-do-i-set-a-gender/index.md)
--- title: How Do I Set a Gender? description: > DiceBear has no single gender switch, but you can shape avatars to look more masculine or feminine by setting each style's options, and soon by filtering variants with tags. Here is how, plus where to share and reuse option sets. ---
How do I set a gender?
DiceBear has no single genderswitch, but you can shape any avatar to look more masculine or feminine. Every feature is its own option you can set directly, so you pick the traits that fit the look you want, such as the hair or facial hair, and leave out the rest. An upcoming release adds descriptive variant tags that turn the common cases into a one-liner.
Find and apply the options
The Playground shows a preview for every option value and lets you combine them, with the avatar updating as you go. Every avatar style page lists the same options as a static reference, also with previews, so you can look them up at any time. If you would rather not write any code, the Editor lets you browse styles and adjust options visually.
Once you know which options you want, pass them as query parameters in the HTTP API or as options in the JS library and the other libraries. The Avataaars style, for example, lets you turn facial hair off withfacialHairProbability=0:
text
https://api.dicebear.com/10.x/avataaars/svg?seed=Casey&facialHairProbability=0
The options differ from style to style, so check the style page for the one you use.
Filter by tags
::: warning The character tags are not available yet
No DiceBear style carries tags such as hairLength or facialHairtoday, so the filters in this section have no effect for now. Until they ship, set the per-feature options described above.
:::
An upcoming release tags the character styles' variants with descriptive labels such ashairLength:long or headwear:headscarf. Thetagsoption keeps only the variants you choose, which will often be the quickest way to lean on the features that read as more masculine or feminine. For example, keep long hair and leave out facial hair:
js
const avatar = new Avatar(style, { seed: 'Casey', tags: ['hairLength:long', '!facialHair'], });
The same filter works as a query parameter in the HTTP API:
text
https://api.dicebear.com/10.x/adventurer/svg?seed=Casey&tags=hairLength:long,!facialHair
Tags and the per-feature options work together, so you can combine a tag filter with options such asfacialHairProbability. See Filter variants with tags for how the filter behaves and which tags are already available.
Share and reuse option sets
If you put together a set of options you like, share it under Show and tell in our GitHub Discussions. Other people can then build on your work and adapt it to their own needs, and you can reuse combinations that others have already shared.
Why there is no dedicated gender option
Every DiceBear option names something that is drawn: a hairstyle, a beard, glasses, a hat. None of those features belongs to a gender. Whether long hair, a headscarf, or earrings reads as masculine or feminine is a matter of convention, and conventions differ by culture and by personal taste.
A male/femaleswitch would have to settle on one such convention for everyone. DiceBear is used all over the world, in every kind of project, so a fixed mapping would be wrong for a good part of that audience, and the library would be the one deciding what a man or a woman looks like. That call belongs to your project, not to us.
Facial hair is the feature that comes closest to a signal, and it still says little. People grow a beard or shave it for reasons of taste, culture, and religion, so its presence describes the drawing rather than the person.
No option is tied to a gender unless the style's designer deliberately built it that way. The options describe features such as hair or glasses, and what you make of them is up to you.
---
Apps/Docs/Pages/Guides/How Many Unique Avatars/Index (apps/docs/pages/guides/how-many-unique-avatars/index.md)
--- title: How Many Unique Avatars Are Possible? description: > Find out how many unique seed-driven avatar combinations are possible for each DiceBear avatar style at default configuration. ---
<script setup lang="ts"> import UniqueAvatarsTable from '@theme/components/guides/UniqueAvatarsTable.vue'; </script>
How many unique avatars are possible per avatar style?
The number below is the size of the seed-driven output space for each style at its default configuration: how many distinct avatars the seed can produce while every other option is left untouched. The count mirrors what the renderer actually does:
- Variant pick per component. Each visible component contributes one variant choice. Variants withweight: 0are excluded because the PRNG never picks them (unless every variant hasweight: 0, in which case the PRNG falls back to an unweighted pick across all of them). - Probability. A component whoseprobability is strictly between 0and100adds the "not rendered" branch as one extra outcome. A component withprobability: 0collapses to a single (always-absent) outcome. - Per-component transforms.rotate, scale, and translateranges in the definition are sampled with 4-decimal precision per component reference, so a[min, max] range contributes round((max - min) × 10000) + 1distinct values. - Color palettes. Color groups are evaluated jointly:notEqualTostrips the picked hex values of the referenced groups (with the renderer's "fall back to full palette when filtering empties" rule), andcontrastToreduces to a single, deterministic pick. - Seed-derived initials. When a style renders theinitial or initialsvariable, each output letter ranges over the Unicode\p{L}category (about 140,000 distinct uppercased characters), andinitialsemits up to two letters per seed.
User-supplied options (custom color palettes, variant allowlists, additional backgrounds,flip, rotate, scale, translate, borderRadius, ID randomization, …) raise the count further beyond what is reported here.
<UniqueAvatarsTable />
If a number looks wrong, please open a discussion on GitHub.
---
Apps/Docs/Pages/Guides/Load All Avatar Styles/Index (apps/docs/pages/guides/load-all-avatar-styles/index.md)
--- title: Load All Avatar Styles from @dicebear/styles description: > Learn how to load every avatar style shipped with @dicebear/styles at once in Node.js, PHP, Python, Rust, Go and Dart. ---
How to load all avatar styles from @dicebear/styles?
The DiceBear styles repository ships every official avatar style as a separate JSON file. It is distributed as@dicebear/styleson npm,dicebear/styleson Packagist,dicebear-styleson PyPI,dicebear-styleson crates.io,github.com/dicebear/styles/v10as a Go module anddicebear_styleson pub.dev. Most projects only need one or two styles, but sometimes (for a style picker, a gallery page, or a batch job) you want to load all of them at once.
This guide shows how to do that in Node.js, PHP, Python, Rust, Go and Dart.
Node.js
In Node.js you can read the styles straight from the installed package on disk. The package ships its source JSON files undersrc/.
js
import { readdir, readFile } from 'node:fs/promises'; import { createRequire } from 'node:module'; import path from 'node:path'; import { Avatar } from '@dicebear/core'; const require = createRequire(import.meta.url); const stylesDir = path.join( path.dirname(require.resolve('@dicebear/styles/package.json')), 'src', ); const files = (await readdir(stylesDir)).filter((file) => file.endsWith('.json'), ); const styles = Object.fromEntries( await Promise.all( files.map(async (file) => { const definition = JSON.parse( await readFile(path.join(stylesDir, file), 'utf8'), ); return [path.basename(file, '.json'), definition]; }), ), );const avatar = new Avatar(styles.lorelei, { seed: 'Alice' });
PHP
PHP can locate the installed package via Composer and iterate over the JSON files in itssrc/ directory.
php
<?php use Composer\InstalledVersions; use DiceBear\Avatar; use DiceBear\Style; $basePath = InstalledVersions::getInstallPath('dicebear/styles'); $files = glob($basePath . '/src/*.json'); $styles = []; foreach ($files as $file) { $name = basename($file, '.json'); $styles[$name] = Style::fromJson(file_get_contents($file)); }$avatar = new Avatar($styles['lorelei'], ['seed' => 'Alice']);
Python
The dicebear-stylespackage ships the definitions as JSON resources under thedicebear_styles import name. Iterate over them with importlib.resources.
python
from importlib.resources import files from dicebear import Avatar, Style styles = { resource.name.removesuffix(".json"): Style.from_json( resource.read_text("utf-8") ) for resource in files("dicebear_styles").iterdir() if resource.name.endswith(".json") }avatar = Avatar(styles["lorelei"], {"seed": "Alice"})
Rust
The dicebear-stylescrate embeds each style behind a Cargo feature of the same name, so a binary only ships the styles it opts into. To load _all_ of them, add the crate with theall feature:
sh
cargo add dicebear-core serde_json cargo add dicebear-styles --features all
dicebear_styles::all()lists every style compiled into the build, anddicebear_styles::get(name) returns its raw JSON definition.
rust
use std::collections::HashMap; use dicebear_core::{Avatar, Style}; use serde_json::json; let mut styles = HashMap::new(); for name in dicebear_styles::all() { let definition = dicebear_styles::get(name).expect("style is embedded"); styles.insert(name, Style::from_str(definition)?); }let avatar = Avatar::new(&styles["lorelei"], json!({ "seed": "Alice" }))?;
Go
The github.com/dicebear/styles/v10module embeds every style. Unlike the Rust crate, there is no per-style opt-in, so the whole set is available once the module is added.
sh
go get github.com/dicebear/dicebear-go/v10 go get github.com/dicebear/styles/v10
styles.All() lists every embedded style and styles.Get(name)returns its raw JSON definition.
go
import ( dicebear "github.com/dicebear/dicebear-go/v10" "github.com/dicebear/styles/v10" ) parsed := map[string]*dicebear.Style{} for _, name := range styles.All() { definition, _ := styles.Get(name) style, err := dicebear.NewStyle([]byte(definition)) if err != nil { panic(err) } parsed[name] = style }avatar, _ := dicebear.NewAvatar(parsed["lorelei"], map[string]any{"seed": "Alice"})
Dart
The dicebear_stylespackage ships each style in its own library, so a compiled app only embeds the styles it imports. To load _all_ of them, import the umbrella librarypackage:dicebear_styles/dicebear_styles.dart, which re-exports every style:
sh
dart pub add dicebear_core dicebear_styles
styles.all lists every embedded style and styles.get(name)returns its raw JSON definition.
dart
import 'package:dicebear_core/dicebear_core.dart'; import 'package:dicebear_styles/dicebear_styles.dart' as styles; final parsed = { for (final name in styles.all) name: Style.parse(styles.get(name)!), };final avatar = Avatar(parsed['lorelei']!, {'seed': 'Alice'});
---
Apps/Docs/Pages/Guides/Use As Avatar Placeholder/Index (apps/docs/pages/guides/use-as-avatar-placeholder/index.md)
--- title: Using DiceBear as an Avatar Placeholder API description: > Use DiceBear as a deterministic avatar placeholder API for user profiles. Generate consistent SVG profile pictures from user IDs or emails, with no image upload required. ---
<script setup> import { useData } from 'vitepress'; import { Fingerprint, Zap, Server, Palette } from '@lucide/vue'; import BrowserPreview from '@theme/components/ui/UiBrowserPreview.vue'; import DocsHighlights from '@theme/components/docs/DocsHighlights.vue'; import DocsStyleGrid from '@theme/components/docs/DocsStyleGrid.vue';
const { theme } = useData();
const highlights = [ { icon: Fingerprint, title: 'Deterministic', description: 'The same seed always produces the same avatar. Use a user ID or email as the seed and the placeholder stays consistent across sessions and devices.', color: '#1689cc', }, { icon: Zap, title: 'Zero upload required', description: 'No images to store, no moderation needed. The avatar is generated on the fly, which works well for new users without a profile picture yet.', color: '#f59e0b', }, { icon: Server, title: 'Self-hostable', description: 'Run your own instance of the HTTP API for full control over availability and data retention.', color: '#22c55e', }, { icon: Palette, title:${theme.value.styleCount} styles, description: 'Pick the visual style that fits your product, from abstract geometric shapes to illustrated characters.', color: '#a855f7', }, ];
const styles = [ { name: 'Initials', styleName: 'initials', link: '/styles/initials/', bestFor: 'Apps where showing user initials is conventional', }, { name: 'Identicon', styleName: 'identicon', link: '/styles/identicon/', bestFor: 'Developer tools, version control, technical platforms', }, { name: 'Pixel Art', styleName: 'pixel-art', link: '/styles/pixel-art/', bestFor: 'Gaming, retro, or developer-focused communities', }, { name: 'Thumbs', styleName: 'thumbs', link: '/styles/thumbs/', bestFor: 'Friendly consumer apps and social platforms', }, { name: 'Shapes', styleName: 'shapes', link: '/styles/shapes/', bestFor: 'Abstract, neutral placeholder for any context', }, ]; </script>
Using DiceBear as an avatar placeholder API
An avatar placeholder replaces the generic default shown when a user hasn't uploaded a profile picture yet. Instead of a gray silhouette, DiceBear generates a unique, deterministic SVG avatar from any seed, so every user gets a distinct picture from the moment they sign up.
Why DiceBear as a placeholder?
<DocsHighlights :highlights="highlights" />
With the HTTP API
The simplest approach: use a DiceBear API URL as the src of an <img>tag. Use a stable identifier as the seed. A numeric user ID works well. For full options and rate limit details, see the HTTP API documentation.
<BrowserPreview url="https://api.dicebear.com/10.x/initials/svg?seed=JD" /> <BrowserPreview url="https://api.dicebear.com/10.x/pixel-art/svg?seed=user-42" />
html
<img src="https://api.dicebear.com/10.x/initials/svg?seed=JD" alt="User avatar" width="48" height="48" />
Fallback on image error
Combine DiceBear with an onerrorhandler to fall back gracefully when a user's uploaded photo fails to load:
html
<img src="/uploads/user-123.jpg" onerror="this.src='https://api.dicebear.com/10.x/pixel-art/svg?seed=123'; this.onerror=null;" alt="User avatar" />
Using a user ID as seed
Pass a stable, unique identifier as the seed to ensure each user always gets the same placeholder:
js
const userId = 'user-8f3a2c'; const avatarUrl = https://api.dicebear.com/10.x/thumbs/svg?seed=${encodeURIComponent(userId)};
<BrowserPreview url="https://api.dicebear.com/10.x/thumbs/svg?seed=user-8f3a2c" />
With the JavaScript library
Use the JS library for server-side rendering or to embed the SVG directly in your markup without an additional HTTP request. For full installation and API details, see the JavaScript library documentation.
js
import { Style, Avatar } from '@dicebear/core'; import thumbs from '@dicebear/styles/thumbs.json' with { type: 'json' }; const style = new Style(thumbs);function getPlaceholderAvatar(userId) { return new Avatar(style, { seed: userId, size: 48, borderRadius: 50, }).toString(); }
With the PHP library
Use the PHP library for server-side rendering without an additional HTTP request. For full installation and API details, see the PHP library documentation.
php
<?php use Composer\InstalledVersions; use DiceBear\Style; use DiceBear\Avatar; $basePath = InstalledVersions::getInstallPath('dicebear/styles'); $style = Style::fromJson(file_get_contents($basePath . '/src/thumbs.json'));function getPlaceholderAvatar(Style $style, string $userId): string { return (string) new Avatar($style, [ 'seed' => $userId, 'size' => 48, 'borderRadius' => 50, ]); }
With the Python library
Use the Python library for server-side rendering without an additional HTTP request. For full installation and API details, see the Python library documentation.
python
from importlib.resources import files from dicebear import Avatar, Style style = Style.from_json( files("dicebear_styles").joinpath("thumbs.json").read_text("utf-8") )def get_placeholder_avatar(user_id: str) -> str: return Avatar(style, { "seed": user_id, "size": 48, "borderRadius": 50, }).to_string()
With the Rust library
Use the Rust library for server-side rendering without an additional HTTP request. For full installation and API details, see the Rust library documentation.
rust
use dicebear_core::{Avatar, Error, Style}; use serde_json::json; let style = Style::from_str(dicebear_styles::THUMBS)?; fn placeholder_avatar(style: &Style, user_id: &str) -> Result<String, Error> { let avatar = Avatar::new(style, json!({ "seed": user_id, "size": 48, "borderRadius": 50, }))?; Ok(avatar.to_string()) }
With the Go library
Use the Go library for server-side rendering without an additional HTTP request. For full installation and API details, see the Go library documentation.
go
import ( dicebear "github.com/dicebear/dicebear-go/v10" "github.com/dicebear/styles/v10" ) style, _ := dicebear.NewStyle([]byte(styles.Thumbs)) func placeholderAvatar(style *dicebear.Style, userID string) (string, error) { avatar, err := dicebear.NewAvatar(style, map[string]any{ "seed": userID, "size": 48, "borderRadius": 50, }) if err != nil { return "", err } return avatar.SVG(), nil }
With the Dart library
Use the Dart library for server-side rendering without an additional HTTP request. For full installation and API details, see the Dart library documentation.
dart
import 'package:dicebear_core/dicebear_core.dart'; import 'package:dicebear_styles/thumbs.dart'; final style = Style.parse(thumbs);String getPlaceholderAvatar(String userId) { return Avatar(style, { 'seed': userId, 'size': 48, 'borderRadius': 50, }).svg; }
Choosing a style
Different styles suit different use cases. Click a style to see all available options.
<DocsStyleGrid :styles="styles" />
Tip: always define a size
Specify a size or CSS dimensions to avoid layout shift while the avatar loads:
js
// JS library new Avatar(style, { seed: userId, size: 48, borderRadius: 50 });
php
// PHP library new Avatar($style, ['seed' => $userId, 'size' => 48, 'borderRadius' => 50]);
python
Python library Avatar(style, {"seed": user_id, "size": 48, "borderRadius": 50})
rust
// Rust library Avatar::new(&style, json!({ "seed": user_id, "size": 48, "borderRadius": 50 }))?;
go
// Go library dicebear.NewAvatar(style, map[string]any{"seed": userID, "size": 48, "borderRadius": 50})
dart
// Dart library Avatar(style, {'seed': userId, 'size': 48, 'borderRadius': 50});
text
// HTTP API https://api.dicebear.com/10.x/thumbs/svg?seed=user-123&size=48&borderRadius=50
---
Apps/Docs/Pages/Guides/Use The Http Api As Gravatar Default Image/Index (apps/docs/pages/guides/use-the-http-api-as-gravatar-default-image/index.md)
--- title: DiceBear as Gravatar Default Avatar description: > Use DiceBear's avatar API as a privacy-focused Gravatar fallback image. Simple URL-based integration with no authentication required. ---
DiceBear as Gravatar default avatar
You can use the HTTP API of DiceBear as Gravatar default image. But before that, let's take a look at the conditions for Gravatar default images:
1. ✅ MUST be publicly available (e.g. cannot be on an intranet, on a local
development machine, behind HTTP Auth or some other firewall etc). Default images are passed through a security scan to avoid malicious content. 2. ✅ MUST be accessible via HTTP or HTTPS on the standard ports, 80 and 443, respectively. 3. ⚠️ MUST have a recognizable image extension (jpg, jpeg, gif, png, heic) 4. ⚠️ MUST NOT include a querystring (if it does, it will be ignored) Source: https://docs.gravatar.com/sdk/images/#default-image Since Gravatar does not support SVG, we have to use the PNG endpoint. ::: code-group
`js [JavaScript] const emailHash = encodeURIComponent('00000000000000000000000000000000'); const defaultImage = encodeURIComponent( 'https://api.dicebear.com/10.x/lorelei/svg' // [!code --] 'https://api.dicebear.com/10.x/lorelei/png' // [!code ++] );
const gravatarImage = https://www.gravatar.com/avatar/${emailHash}?d=${defaultImage}; // https://www.gravatar.com/avatar/00000000000000000000000000000000?d=https%3A%2F%2Fapi.dicebear.com%2F10.x%2Florelei%2Fpng
text
php [PHP] $emailHash = urlencode('00000000000000000000000000000000'); $defaultImage = urlencode( 'https://api.dicebear.com/10.x/lorelei/svg' // [!code --] 'https://api.dicebear.com/10.x/lorelei/png' // [!code ++] ); $gravatarImage = sprintf( 'https://www.gravatar.com/avatar/%s?d=%s', $emailHash, $defaultImage ); // https://www.gravatar.com/avatar/00000000000000000000000000000000?d=https%3A%2F%2Fapi.dicebear.com%2F10.x%2Florelei%2Fpng text python [Python] import urllib.parse email_hash = urllib.parse.quote("00000000000000000000000000000000") default_image = urllib.parse.quote( "https://api.dicebear.com/10.x/lorelei/svg" # [!code --] "https://api.dicebear.com/10.x/lorelei/png" # [!code ++] ) gravatar_image = f"https://www.gravatar.com/avatar/{email_hash}?d={default_image}" https://www.gravatar.com/avatar/00000000000000000000000000000000?d=https%3A%2F%2Fapi.dicebear.com%2F10.x%2Florelei%2Fpng text go [Go] import ( "fmt" "net/url" ) emailHash := url.QueryEscape("00000000000000000000000000000000") defaultImage := url.QueryEscape( "https://api.dicebear.com/10.x/lorelei/svg", // [!code --] "https://api.dicebear.com/10.x/lorelei/png", // [!code ++] ) gravatarImage := fmt.Sprintf("https://www.gravatar.com/avatar/%s?d=%s", emailHash, defaultImage) // https://www.gravatar.com/avatar/00000000000000000000000000000000?d=https%3A%2F%2Fapi.dicebear.com%2F10.x%2Florelei%2Fpng text dart [Dart] final emailHash = Uri.encodeComponent('00000000000000000000000000000000'); final defaultImage = Uri.encodeComponent( 'https://api.dicebear.com/10.x/lorelei/svg' // [!code --] 'https://api.dicebear.com/10.x/lorelei/png' // [!code ++] ); final gravatarImage = 'https://www.gravatar.com/avatar/$emailHash?d=$defaultImage'; // https://www.gravatar.com/avatar/00000000000000000000000000000000?d=https%3A%2F%2Fapi.dicebear.com%2F10.x%2Florelei%2Fpng text ::: Usually we set options in the query string, such as the seed. Since a query string is not allowed by Gravatar, the HTTP-API allows you to specify the options in the path. Just replace the question mark with a slash and encode the options.::: code-group js [JavaScript] const emailHash = encodeURIComponent('00000000000000000000000000000000'); const options =seed=${emailHash}; const defaultImage = encodeURIComponent(https://api.dicebear.com/10.x/lorelei/png?${options}// [!code --]https://api.dicebear.com/10.x/lorelei/png/${encodeURIComponent(options)}, // [!code ++] );
const gravatarImage = https://www.gravatar.com/avatar/${emailHash}?d=${defaultImage}; // https://www.gravatar.com/avatar/00000000000000000000000000000000?d=https%3A%2F%2Fapi.dicebear.com%2F10.x%2Florelei%2Fpng%2Fseed%253D00000000000000000000000000000000
text
php [PHP] $emailHash = urlencode('00000000000000000000000000000000'); $options = sprintf('seed=%s', $emailHash); $defaultImage = urlencode( 'https://api.dicebear.com/10.x/lorelei/png?' . $options // [!code --] 'https://api.dicebear.com/10.x/lorelei/png/' . urlencode($options) // [!code ++] ); $gravatarImage = sprintf( 'https://www.gravatar.com/avatar/%s?d=%s', $emailHash, $defaultImage ); // https://www.gravatar.com/avatar/00000000000000000000000000000000?d=https%3A%2F%2Fapi.dicebear.com%2F10.x%2Florelei%2Fpng%2Fseed%253D00000000000000000000000000000000 text python [Python] import urllib.parse email_hash = urllib.parse.quote("00000000000000000000000000000000") options = f"seed={email_hash}" default_image = urllib.parse.quote( f"https://api.dicebear.com/10.x/lorelei/png?{options}" # [!code --] f"https://api.dicebear.com/10.x/lorelei/png/{urllib.parse.quote(options)}" # [!code ++] ) gravatar_image = f"https://www.gravatar.com/avatar/{email_hash}?d={default_image}" https://www.gravatar.com/avatar/00000000000000000000000000000000?d=https%3A%2F%2Fapi.dicebear.com%2F10.x%2Florelei%2Fpng%2Fseed%253D00000000000000000000000000000000 text go [Go] import ( "fmt" "net/url" ) emailHash := url.QueryEscape("00000000000000000000000000000000") options := fmt.Sprintf("seed=%s", emailHash) defaultImage := url.QueryEscape( fmt.Sprintf("https://api.dicebear.com/10.x/lorelei/png?%s", options), // [!code --] fmt.Sprintf("https://api.dicebear.com/10.x/lorelei/png/%s", url.QueryEscape(options)), // [!code ++] ) gravatarImage := fmt.Sprintf("https://www.gravatar.com/avatar/%s?d=%s", emailHash, defaultImage) // https://www.gravatar.com/avatar/00000000000000000000000000000000?d=https%3A%2F%2Fapi.dicebear.com%2F10.x%2Florelei%2Fpng%2Fseed%253D00000000000000000000000000000000 text dart [Dart] final emailHash = Uri.encodeComponent('00000000000000000000000000000000'); final options = 'seed=$emailHash'; final defaultImage = Uri.encodeComponent( 'https://api.dicebear.com/10.x/lorelei/png?$options' // [!code --] 'https://api.dicebear.com/10.x/lorelei/png/${Uri.encodeComponent(options)}' // [!code ++] ); final gravatarImage = 'https://www.gravatar.com/avatar/$emailHash?d=$defaultImage'; // https://www.gravatar.com/avatar/00000000000000000000000000000000?d=https%3A%2F%2Fapi.dicebear.com%2F10.x%2Florelei%2Fpng%2Fseed%253D00000000000000000000000000000000 text ::: --- Apps/Docs/Pages/Guides/Use The Library With Angular/Index (apps/docs/pages/guides/use-the-library-with-angular/index.md) --- title: Angular Avatar Library – DiceBear Integration description: > Integrate DiceBear SVG profile pictures into Angular applications via the JavaScript avatar library or avatar API. --- Angular avatar library: using DiceBear with Angular DiceBear can be integrated into Angular components using Signals (Angular 17+) or the OnChanges lifecycle hook. Use the JavaScript library for client-side SVG avatar generation, or the HTTP API as a simple <img> source with no additional dependencies. You can use DiceBear with Angular either via the JS-Library or the HTTP-API. With the JS library ::: code-group typescript [Angular 17+] import { Component, input, computed } from '@angular/core'; import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei);
@Component({ selector: 'app-avatar', template:<img [src]="avatarUrl()" alt="Avatar" />, }) export class AvatarComponent { seed = input('Alice');
avatarUrl = computed(() => new Avatar(style, { seed: this.seed(), size: 128, // ... other options }).toDataUri(), ); }
text
typescript [Angular 16 and earlier] import { Component, Input, OnChanges } from '@angular/core'; import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei);
@Component({ selector: 'app-avatar', standalone: true, template:<img [src]="avatarUrl" alt="Avatar" />, }) export class AvatarComponent implements OnChanges { @Input() seed: string = 'Alice'; avatarUrl: string = '';
ngOnChanges() { this.avatarUrl = new Avatar(style, { seed: this.seed, size: 128, // ... other options }).toDataUri(); } }
text
::: With the HTTP API ::: code-group
typescript [Angular 17+] import { Component, input, computed } from '@angular/core';
@Component({ selector: 'app-avatar', template:<img [src]="avatarUrl()" alt="Avatar" />, }) export class AvatarComponent { seed = input('Alice');
avatarUrl = computed(() => { const url = new URL('https://api.dicebear.com/10.x/lorelei/svg'); url.searchParams.set('seed', this.seed()); url.searchParams.set('size', '128'); // ... other options return url.href; }); }
text
typescript [Angular 16 and earlier] import { Component, Input, OnChanges } from '@angular/core';
@Component({ selector: 'app-avatar', standalone: true, template:<img [src]="avatarUrl" alt="Avatar" />, }) export class AvatarComponent implements OnChanges { @Input() seed: string = 'Alice'; avatarUrl: string = '';
ngOnChanges() { const url = new URL('https://api.dicebear.com/10.x/lorelei/svg'); url.searchParams.set('seed', this.seed); url.searchParams.set('size', '128'); // ... other options this.avatarUrl = url.href; } }
text
::: --- Apps/Docs/Pages/Guides/Use The Library With Flutter/Index (apps/docs/pages/guides/use-the-library-with-flutter/index.md) --- title: Flutter Avatar Library description: > Generate SVG profile pictures in Flutter with DiceBear. Render avatars on the device with the Dart library, or load PNGs from the HTTP API with no extra packages. --- Flutter avatar library: using DiceBear with Flutter You can generate DiceBear avatars in Flutter two ways. Use the Dart library with an SVG renderer to build avatars on the device, or use the HTTP API with Flutter's built-in Image.network to load ready-made PNGs. The HTTP API needs no extra packages and is the quickest to set up. The Dart library keeps everything local, so it works offline and sends no requests. With the Dart library Add the core library, the style definitions, and an SVG renderer. We use flutter_svg to draw the SVG string.
sh flutter pub add dicebear_core dicebear_styles flutter_svg text dart import 'package:flutter/material.dart'; import 'package:flutter_svg/flutter_svg.dart'; import 'package:dicebear_core/dicebear_core.dart'; import 'package:dicebear_styles/lorelei.dart'; // Parse the style once and reuse it. final style = Style.parse(lorelei); class UserAvatar extends StatelessWidget { const UserAvatar({super.key, this.seed = 'Alice'}); final String seed; @override Widget build(BuildContext context) { final avatar = Avatar(style, { 'seed': seed, 'size': 128, // ... other options }); return SvgPicture.string( avatar.svg, width: 128, height: 128, ); } } text Avatar(style, {...}).svg returns the SVG as a string, which SvgPicture.string renders directly. For the full API and the options each style accepts, see the Dart library reference. With the HTTP API The HTTP API returns finished images, so you need no extra packages. Request the png format and pass the URL to Image.network. dart import 'package:flutter/material.dart'; class UserAvatar extends StatelessWidget { const UserAvatar({super.key, this.seed = 'Alice'}); final String seed; @override Widget build(BuildContext context) { final url = Uri.https('api.dicebear.com', '/10.x/lorelei/png', { 'seed': seed, 'size': '128', // ... other options }); return Image.network( url.toString(), width: 128, height: 128, ); } } text Every option is a query parameter. See the HTTP API reference for the full list. --- Apps/Docs/Pages/Guides/Use The Library With Next Js/Index (apps/docs/pages/guides/use-the-library-with-next-js/index.md) --- title: Next.js Avatar Library – DiceBear Integration description: > Use DiceBear SVG avatars in Next.js (App Router and Pages Router). Server component rendering, client component rendering, and image optimization patterns for deterministic profile pictures. --- Next.js avatar library: using DiceBear with Next.js DiceBear works in every Next.js rendering mode: server components, client components, and the Pages Router. Server-side generation is the default recommendation because it produces zero JavaScript on the client and avoids hydration pitfalls. You can use DiceBear with Next.js via the JS-Library or the HTTP-API. App Router Server component (recommended) In App Router, components are server components by default. Generate the SVG on the server and inline it as a data URI, so the avatar needs no client-side JavaScript. tsx // app/components/UserAvatar.tsx import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); export function UserAvatar({ seed = 'Alice' }: { seed?: string }) { const dataUri = new Avatar(style, { seed, size: 128, // ... other options }).toDataUri(); return <img src={dataUri} alt="Avatar" width={128} height={128} />; } text Client component Mark the file with 'use client' and wrap generation in useMemo so the avatar is only re-derived when the seed changes. tsx // app/components/UserAvatarClient.tsx 'use client'; import { useMemo } from 'react'; import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); export function UserAvatarClient({ seed = 'Alice' }: { seed?: string }) { const dataUri = useMemo( () => new Avatar(style, { seed, size: 128, // ... other options }).toDataUri(), [seed], ); return <img src={dataUri} alt="Avatar" width={128} height={128} />; } text ::: warning Hydration & idRandomizationidRandomization uses the host's non-seeded RNG, so the server and the client will produce different IDs and React will throw a hydration mismatch warning. Either: - Generate the avatar in a server component (no hydration) and don't pass the SVG to a client component, or - Leave idRandomization: false and rely on the deterministic IDs. If you need ID uniqueness across multiple avatars on the same page, render each avatar entirely on the server. ::: Route handler (avatar endpoint) Expose DiceBear behind your own URL. This is useful for caching with custom Cache-Control headers or for restricting which seeds are accepted. ts // app/api/avatar/[seed]/route.ts import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); export async function GET( _request: Request, { params }: { params: Promise<{ seed: string }> }, ) { const { seed } = await params; const svg = new Avatar(style, { seed, size: 128 }).toString(); return new Response(svg, { headers: { 'Content-Type': 'image/svg+xml', 'Cache-Control': 'public, max-age=31536000, immutable', }, }); } text Pages Router Pages Router treats every component as client-side by default. Use useMemo exactly like in a plain React app. See the React guide for the canonical pattern. Server-side generation through getServerSideProps or getStaticProps returns the SVG as a prop, which avoids a client bundle hit. tsx // pages/profile.tsx import type { GetServerSideProps } from 'next'; import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); type Props = { avatar: string }; export const getServerSideProps: GetServerSideProps<Props> = async () => { const avatar = new Avatar(style, { seed: 'Alice', size: 128 }).toDataUri(); return { props: { avatar } }; }; export default function Profile({ avatar }: Props) { return <img src={avatar} alt="Avatar" width={128} height={128} />; } text With the HTTP API The HTTP API needs no installation and works in both routers. Use a plain <img> tag. Next.js does not pre-process external SVGs by default. tsx export function UserAvatar({ seed = 'Alice' }: { seed?: string }) { const src =https://api.dicebear.com/10.x/lorelei/svg?seed=${encodeURIComponent(seed)}&size=128; return <img src={src} alt="Avatar" width={128} height={128} />; } text If you want to use next/image with the HTTP API, request a raster format (PNG, WebP, AVIF), since next/image does not optimize SVG sources, and add api.dicebear.com to images.remotePatterns in next.config.js. js // next.config.js module.exports = { images: { remotePatterns: [{ protocol: 'https', hostname: 'api.dicebear.com' }], }, }; text tsx import Image from 'next/image';
export function UserAvatar({ seed = 'Alice' }: { seed?: string }) { const src =https://api.dicebear.com/10.x/lorelei/png?seed=${encodeURIComponent(seed)}&size=128;
return <Image src={src} alt="Avatar" width={128} height={128} />; }
text
--- Apps/Docs/Pages/Guides/Use The Library With Nuxt/Index (apps/docs/pages/guides/use-the-library-with-nuxt/index.md) --- title: Nuxt Avatar Library – DiceBear Integration description: > Use DiceBear SVG avatars in Nuxt 3. Server-side rendering, client-side rendering, and Nitro endpoint patterns for deterministic profile pictures. --- Nuxt avatar library: using DiceBear with Nuxt DiceBear works with Nuxt's universal rendering model. The avatar can be generated on the server during SSR, in a Nitro endpoint, or in a plain client component. Pick whichever matches the page's rendering mode. You can use DiceBear with Nuxt via the JS-Library or the HTTP-API. With the JS library Universal component Wrap generation in computed and the avatar is produced on whichever side the component renders on. Because the result is a data URI, the markup hydrates without re-running the renderer on the client.
vue <script setup lang="ts"> import { computed } from 'vue'; import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); const props = defineProps<{ seed?: string }>(); const avatar = computed(() => new Avatar(style, { seed: props.seed ?? 'Alice', size: 128, // ... other options }).toDataUri(), ); </script> <template> <img :src="avatar" alt="Avatar" width="128" height="128" /> </template> text ::: warning Hydration & idRandomizationidRandomization is backed by the host's non-seeded RNG, so the IDs produced during SSR will not match the client re-render, and Vue logs a hydration mismatch. Keep idRandomization: false for SSR'd avatars, or wrap the component in <ClientOnly> and accept the visual flash. If you need unique IDs across multiple avatars on the same page, render the entire page server-side and skip client hydration of the avatar subtree. ::: Nitro endpoint Expose DiceBear behind your own URL when you want custom caching or seed validation: ts // server/api/avatar/[seed].get.ts import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); export default defineEventHandler((event) => { const seed = getRouterParam(event, 'seed') ?? ''; setHeader(event, 'Content-Type', 'image/svg+xml'); setHeader(event, 'Cache-Control', 'public, max-age=31536000, immutable'); return new Avatar(style, { seed, size: 128 }).toString(); }); text Consume it from any component with <img :src="/api/avatar/${seed}">. Cache with useAsyncData For per-request SSR caching (so the same seed isn't re-rendered when multiple components ask for it), wrap generation in useAsyncData: vue <script setup lang="ts"> import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); const props = defineProps<{ seed: string }>();
const { data: avatar } = await useAsyncData(avatar:${props.seed}, () => Promise.resolve( new Avatar(style, { seed: props.seed, size: 128 }).toDataUri(), ), ); </script>
<template> <img :src="avatar ?? undefined" alt="Avatar" width="128" height="128" /> </template>
text
With the HTTP API The HTTP API needs no installation. The URL is the same on the server and in the browser, so <img> works in any rendering mode:
vue <script setup lang="ts"> import { computed } from 'vue'; const props = defineProps<{ seed?: string }>(); const src = computed(() => { const url = new URL('https://api.dicebear.com/10.x/lorelei/svg'); url.searchParams.set('seed', props.seed ?? 'Alice'); url.searchParams.set('size', '128'); return url.href; }); </script> <template> <img :src="src" alt="Avatar" width="128" height="128" /> </template> text --- Apps/Docs/Pages/Guides/Use The Library With React/Index (apps/docs/pages/guides/use-the-library-with-react/index.md) --- title: React Avatar Library – DiceBear Integration description: > Use DiceBear SVG avatars in React via JS library or avatar API. Generate deterministic profile pictures and user placeholder images in React apps. --- React avatar library: using DiceBear with React DiceBear works in React via the JS library or the HTTP API. Use useMemo to generate deterministic SVG profile pictures from a seed, or use the HTTP API as a plain <img src> with no additional dependencies. You can use DiceBear with React either via the JS-Library or the HTTP-API. With the JS library jsx import { useMemo } from 'react'; import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); export default function UserAvatar({ seed = 'Alice' }) { const avatar = useMemo(() => { return new Avatar(style, { seed, size: 128, // ... other options }).toDataUri(); }, [seed]); return <img src={avatar} alt="Avatar" />; } text With the HTTP API jsx import { useMemo } from 'react'; export default function Avatar({ seed = 'Alice' }) { const avatar = useMemo(() => { const url = new URL('https://api.dicebear.com/10.x/lorelei/svg'); url.searchParams.set('seed', seed); url.searchParams.set('size', '128'); // ... other options return url.href; }, [seed]); return <img src={avatar} alt="Avatar" />; } text --- Apps/Docs/Pages/Guides/Use The Library With React Native/Index (apps/docs/pages/guides/use-the-library-with-react-native/index.md) --- title: React Native Avatar Library – DiceBear description: > Generate SVG user avatars in React Native using DiceBear. Integrate the JavaScript avatar library or avatar API into your mobile app. --- React Native avatar library: using DiceBear with React Native DiceBear can be used in React Native via the JavaScript library with an SVG renderer, or via the HTTP API's PNG format using the built-in Image component. The API approach requires no SVG library. You can use DiceBear with React Native either via the JS-Library or the HTTP-API. With the JS library You need an SVG library to render the avatars. In our example we use the package react-native-svg. npm install react-native-svg text jsx import { useMemo } from 'react'; import { View } from 'react-native'; import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; import { SvgXml } from 'react-native-svg'; const style = new Style(lorelei); export default function UserAvatar({ seed = 'Alice' }) { const avatar = useMemo(() => { return new Avatar(style, { seed, size: 128, // ... other options }).toString(); }, [seed]); return ( <View> <SvgXml xml={avatar} /> </View> ); } text With the HTTP API With the HTTP API you can use the PNG format and the built-in Image component without any additional dependencies. jsx import { useMemo } from 'react'; import { Image, View } from 'react-native'; export default function Avatar({ seed = 'Alice' }) { const avatar = useMemo(() => { const url = new URL('https://api.dicebear.com/10.x/lorelei/png'); url.searchParams.set('seed', seed); url.searchParams.set('size', '128'); // ... other options return url.href; }, [seed]); return ( <View> <Image source={{ uri: avatar }} style={{ width: 128, height: 128 }} /> </View> ); } text --- Apps/Docs/Pages/Guides/Use The Library With Svelte/Index (apps/docs/pages/guides/use-the-library-with-svelte/index.md) --- title: Svelte Avatar Library – DiceBear Integration description: > Use DiceBear to generate SVG profile pictures in Svelte via the JavaScript avatar library or avatar API. --- Svelte avatar library: using DiceBear with Svelte DiceBear works with both Svelte 4 and Svelte 5. Use $derived (Svelte 5) or reactive statements (Svelte 4) to keep SVG profile pictures in sync with prop changes, either via the JS library for client-side generation or the HTTP API for a zero-dependency approach. You can use DiceBear with Svelte either via the JS-Library or the HTTP-API. With the JS library ::: code-group svelte [Svelte 5] <script> import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); let { seed = 'Alice' } = $props(); const avatar = $derived( new Avatar(style, { seed, size: 128, // ... other options }).toDataUri() ); </script> <img src={avatar} alt="Avatar" /> text svelte [Svelte 4] <script> import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); export let seed = 'Alice'; $: avatar = new Avatar(style, { seed, size: 128, // ... other options }).toDataUri(); </script> <img src={avatar} alt="Avatar" /> text ::: With the HTTP API ::: code-group svelte [Svelte 5] <script> let { seed = 'Alice' } = $props(); const src = $derived.by(() => { const url = new URL('https://api.dicebear.com/10.x/lorelei/svg'); url.searchParams.set('seed', seed); url.searchParams.set('size', '128'); // ... other options return url.href; }); </script> <img src={src} alt="Avatar" /> text svelte [Svelte 4] <script> export let seed = 'Alice'; let src = ''; $: { const url = new URL('https://api.dicebear.com/10.x/lorelei/svg'); url.searchParams.set('seed', seed); url.searchParams.set('size', '128'); // ... other options src = url.href; } </script> <img src={src} alt="Avatar" /> text ::: --- Apps/Docs/Pages/Guides/Use The Library With Vue/Index (apps/docs/pages/guides/use-the-library-with-vue/index.md) --- title: Vue Avatar Library – DiceBear Integration description: > Add DiceBear SVG avatars to Vue 3 projects via the JavaScript avatar library or avatar API. Includes TypeScript support. --- Vue avatar library: using DiceBear with Vue Wrap avatar generation in a computed property to keep profile pictures in sync with reactive data. Use the JS library for full control, or the HTTP API for a dependency-free approach. You can use DiceBear with Vue either via the JS-Library or the HTTP-API. With the JS library vue <script setup> import { computed } from 'vue'; import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); const props = defineProps({ seed: { type: String, default: 'Alice' }, }); const avatar = computed(() => new Avatar(style, { seed: props.seed, size: 128, // ... other options }).toDataUri(), ); </script> <template> <img :src="avatar" alt="Avatar" /> </template> text With the HTTP API vue <script setup> import { computed } from 'vue'; const props = defineProps({ seed: { type: String, default: 'Alice' }, }); const src = computed(() => { const url = new URL('https://api.dicebear.com/10.x/lorelei/svg'); url.searchParams.set('seed', props.seed); url.searchParams.set('size', '128'); // ... other options return url.href; }); </script> <template> <img :src="src" alt="Avatar" /> </template> text --- Apps/Docs/Pages/How To Use/Cli/Index (apps/docs/pages/how-to-use/cli/index.md) --- title: CLI – Generate Avatars from the Command Line description: > Generate avatars in bulk with the DiceBear CLI. Free command-line avatar generator for creating profile pictures and user placeholder images. All styles supported. --- CLI With the CLI you can generate large numbers of avatars in a single run. Installation Make sure you have Node.js (version 22 or higher) and npm installed. npm install dicebear --global text Upgrade For the latest features and avatar styles, make sure you update the CLI regularly. npm install dicebear --global text Usage Create an avatar Replace <style> with an avatar style name (lowercase, kebab-case for multi-word styles, e.g. lorelei, pixel-art, adventurer-neutral) and [outputPath] with a target directory. If [outputPath] is omitted, the current directory is used as target directory. dicebear <style> [outputPath] text For example, to create an avatar with the lorelei avatar style, use the following command: dicebear lorelei ./avatars text The avatar will be saved as lorelei-0.svg in the ./avatars directory. :::info We provide a large number of avatar styles from different creators. The avatar styles are licensed under different licenses that the creators can choose themselves. For a quick overview we have created a license overview for you. ::: Create multiple avatars You can also create multiple avatars at once with the --count option. Replace <count> with the number of avatars to create. dicebear <style> [outputPath] --count <count> text For example, to create 100 avatars: dicebear lorelei ./avatars --count 100 text This generates files named lorelei-0.svg, lorelei-1.svg, ..., lorelei-99.svg. :::warningThe seed option has no effect in combination with the count option. If count is greater than 1, random values are generated and used as seed to make the avatars differ from each other. ::: :::tip Performance The CLI uses parallel processing based on your CPU cores, so large batches of avatars generate quickly. ::: Output formats You can create avatars in various formats using the --format option: | Format | Description | | ------ | ---------------------------------- | | svg | Scalable Vector Graphics (default) | | png | PNG image | | jpg | JPEG image | | jpeg | JPEG image (alias for jpg) | | webp | WebP image | | avif | AVIF image | | json | JSON with avatar metadata | Example: dicebear lorelei ./avatars --format png text #### Controlling the output image size--size controls the output dimensions (width and height in pixels) for all formats. The default is 512. For rasterized formats (PNG, JPEG, WebP, AVIF) the value is capped at 2048. dicebear lorelei ./avatars --format png --size 256 text #### Adding Exif metadataWhen creating PNG, JPEG, WebP, or AVIF images, you can include Exif metadata: dicebear lorelei ./avatars --format png --exif text #### Saving JSON alongside imagesYou can save a JSON file with avatar metadata alongside each image: dicebear lorelei ./avatars --format png --json text This creates both lorelei-0.png and lorelei-0.json for each avatar. Passing style options Each avatar style has its own customization options. To see all available options for a specific style, use --help: dicebear lorelei --help text Example output: / Detailed source-code truncated for AI context efficiency. / text Example with options: dicebear lorelei ./avatars --backgroundColor b6e3f4,c0aede,d1d4f9 --size 128 text Output file naming Files are named using the pattern {style}-{index}.{format}: - lorelei-0.svg - lorelei-1.png - avataaars-0.webp The index starts at 0 and increments for each avatar created. :::warning File overwrite protection The CLI will not overwrite existing files. If a file already exists at the target path, an error will be thrown. Make sure to use an empty directory or remove existing files before generating new avatars. ::: License banner Before generating avatars, the CLI displays a license banner with information about the style's creator and license: ---------------------------------------------------------------- Lorelei by Lisa Wischofsky Homepage: https://www.instagram.com/lischi_art/ Source: https://www.figma.com/community/file/1198749693280469639 License: CC0 1.0 - https://creativecommons.org/publicdomain/zero/1.0/ ---------------------------------------------------------------- text Show help For general help and a list of all available styles: dicebear --help text / Detailed source-code truncated for AI context efficiency. / text Custom styles You can use any JSON definition file as a style, including your own custom styles or styles exported from the Figma plugin.Just pass the path to the JSON file instead of a style name: dicebear ./my-style.json ./avatars text All available options are automatically detected from the definition. Use --help to see them: dicebear ./my-style.json --help text Generate multiple avatars in PNG format: dicebear ./my-style.json ./avatars --count 20 --format png text Compressing a definition file Definition files exported from the Figma plugin are already compressed on export. A definition you wrote or edited by hand is not, and its path data usually has a lot of room left. --optimize runs the same svgo pass over every element tree in the file and rewrites it in place: dicebear ./my-style.json --optimize text my-style.json 25.5 KB -> 22.1 KB (-12.8%) text Use --optimize-precision to control how many decimals path and transform data keep. The default is 3. Lower values compress harder at the cost of accuracy: dicebear ./my-style.json --optimize --optimize-precision 1 text --optimize-check reports whether the file is optimized without writing anything, and exits with a non-zero status if it is not. This is what you want in continuous integration: dicebear ./my-style.json --optimize-check text Colors, component references, dynamic values, element ids, CSS classes and the contents of <style> elements all survive unchanged, and component width and height are never touched. The CLI verifies this on every run and refuses to write the file if anything moved, so an optimized definition renders the same avatars as before. :::infoOptimizing always rewrites the file in place, so [outputPath] is ignored. Copy the file first if you want to keep the original around. Built-in styles have no definition file of their own and cannot be optimized. ::: Examples Generate a single avatar with a specific seed dicebear avataaars ./avatars --seed "john-doe" text Generate 50 PNG avatars with custom background dicebear bottts ./avatars --count 50 --format png --backgroundColor b6e3f4 text Generate avatars with JSON metadata dicebear pixel-art ./avatars --count 10 --format webp --json text Generate initials avatar dicebear initials ./avatars --seed "Alice" text Troubleshooting "File already exists" error The CLI does not overwrite existing files. Either: - Use an empty output directory - Delete existing files before regenerating Avatar style not found Style names are lowercase, with hyphens for multi-word styles (e.g. pixel-art, adventurer-neutral). Run dicebear --help to see all available styles. Permission denied Make sure you have write permissions to the output directory. On Unix systems, you may need to adjust directory permissions or use sudo for global installation. --- Apps/Docs/Pages/How To Use/Dart Library/Index (apps/docs/pages/how-to-use/dart-library/index.md) --- title: Dart Avatar Library description: > Use the DiceBear Dart library to generate SVG profile pictures in Dart and Flutter. Dart 3.4+ with an API identical to the JavaScript library. --- Dart avatar library The Dart library provides an API identical to the JavaScript library. It requires Dart 3.4 or higher and also works in Flutter apps. The same seed and style definition produce SVGs byte-identical to the JavaScript reference. Installation You need two packages: the core library dicebear_core and the avatar style definitions dicebear_styles. Each style is a string constant in its own library, so a compiled app only embeds the styles it imports. sh dart pub add dicebear_core dart pub add dicebear_styles text In a Flutter project, use flutter pub add instead. Usage We use the avatar style lorelei in our example. You can find more avatar styles here. Each style is exposed as a raw-JSON string (e.g. lorelei from package:dicebear_styles/lorelei.dart) that you hand to Style.parse. dart import 'package:dicebear_core/dicebear_core.dart'; import 'package:dicebear_styles/lorelei.dart'; void main() { final style = Style.parse(lorelei); final avatar = Avatar(style, { 'seed': 'John', // ... other options }); print(avatar.svg); } text Style.parse decodes and validates the raw JSON string. If you already hold a decoded definition (a Map<String, Object?>), pass it to the default Style(...) constructor instead. 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 creators. The avatar styles are licensed under different licenses that the creators can choose themselves. For a quick overview we have created a license overview for you. ::: Deterministic avatars The seed option is the key to generating deterministic avatars. The same seed always produces the same avatar: dart final avatar1 = Avatar(style, {'seed': 'user-123'}); final avatar2 = Avatar(style, {'seed': 'user-123'}); // avatar1.svg == avatar2.svg text Types Style A validated, immutable wrapper around a style definition. Build it once from the decoded definition JSON, then reuse it when generating multiple avatars. Invalid definitions throw a StyleValidationError. dart final style = Style.parse(lorelei); final avatar1 = Avatar(style, {'seed': 'Alice'}); final avatar2 = Avatar(style, {'seed': 'Bob'}); text Avatar The main class for generating avatars. The constructor takes a Style and an optional map of options (invalid options throw an OptionsValidationError, circular color references a CircularColorReferenceError). Omitting the options map is the same as passing an empty one. dart final avatar = Avatar(style, { // ... options }); text OptionsDescriptor Describes all valid options for a given style. Useful for building UIs or validating user input. dart final descriptor = OptionsDescriptor(style).toJson(); text Methods svg / toString() Return type: String Returns the avatar as SVG in XML format. toString() returns the same string, so an Avatar can be used directly in string contexts (string interpolation, print). dart final avatar = Avatar(style, {'seed': 'Alice'}); var svg = avatar.svg; // or svg = avatar.toString(); text toJson() Return type: Map<String, Object?> (with keys svg and options) Returns the SVG and the resolved options as a JSON-encodable map. Pass it to jsonEncode for the serialized form. dart final avatar = Avatar(style, {'seed': 'Alice'}); final result = jsonEncode(avatar.toJson()); // result → {"svg":"<svg>...</svg>","options":{"flip":"none",...}} text The resolved options are also available directly as a map via avatar.resolvedOptions. toDataUri() Return type: String Returns the avatar as data URI. dart final avatar = Avatar(style, {'seed': 'Alice'}); final dataUri = avatar.toDataUri(); // <img src="{dataUri}" alt="Avatar" /> text Core options These options are the same across every DiceBear core. See Core options for the full reference. Here are the options in Dart syntax: dart final avatar = Avatar(style, { 'seed': 'Alice', 'flip': 'horizontal', // 'none', 'horizontal', 'vertical', 'both' 'rotate': 10, // -360 to 360, or [min, max] range 'scale': 0.9, // 0 to 10 (1 = original), or [min, max] range 'borderRadius': 50, // 0-50 (50 = circle) 'size': 128, 'translateX': 0, // -1000 to 1000 (percent of canvas width) 'translateY': 0, // -1000 to 1000 (percent of canvas height) 'idRandomization': true, 'title': 'User Avatar', 'fontFamily': 'Arial', // or ['Arial', 'Helvetica'] 'fontWeight': 700, // 1-1000 'backgroundColor': ['#b6e3f4', '#c0aede'], 'backgroundColorFill': 'solid', // 'solid', 'linear', 'radial' }); text Dynamic component and color options also work the same way. See Dynamic component options for all available patterns. Examples Rendering in Flutter The library has no Flutter dependency; it returns plain strings. To display an avatar in a Flutter widget tree, render the SVG string with a package such as flutter_svg: dart final avatar = Avatar(style, {'seed': 'Alice', 'size': 128}); // In your build method, with package:flutter_svg SvgPicture.string(avatar.svg, width: 128, height: 128); text Avatar with custom background dart final avatar = Avatar(style, { 'seed': 'Alice', 'backgroundColor': ['#b6e3f4', '#c0aede', '#d1d4f9'], }); text Fixed size avatar dart import 'package:dicebear_styles/bottts.dart'; final style = Style.parse(bottts); final avatar = Avatar(style, { 'seed': 'robot-42', 'size': 128, 'borderRadius': 50, // circular avatar }); text Avatar with transformations dart import 'package:dicebear_styles/avataaars.dart'; final style = Style.parse(avataaars); final avatar = Avatar(style, { 'seed': 'Jane', 'flip': 'horizontal', 'rotate': 10, 'scale': 0.9, 'translateY': 5, }); text Multiple avatars on the same page When rendering multiple avatars on the same page, use idRandomization to prevent SVG ID conflicts: dart final style = Style.parse(lorelei); for (final seed in ['alice', 'bob', 'charlie']) { final avatar = Avatar(style, { 'seed': seed, 'idRandomization': true, }); print(avatar.svg); } text Weighted variant selection A weighted map makes some variants more likely than others. The lorelei style selects happy01 or happy02 mouths twice as often as sad01 here: dart final avatar = Avatar(style, { 'seed': 'Alice', 'mouthVariant': {'happy01': 2, 'happy02': 2, 'sad01': 1}, }); text --- Apps/Docs/Pages/How To Use/Go Library/Index (apps/docs/pages/how-to-use/go-library/index.md) --- title: Go Avatar Library description: > Use the DiceBear Go library to generate SVG profile pictures on the server. Go 1.23+ with an API identical to the JavaScript library. --- Go avatar library The Go library provides an API identical to the JavaScript library. It requires Go 1.23 or higher. The same seed and style definition produce SVGs byte-identical to the JavaScript reference. Installation You need two modules: the core library github.com/dicebear/dicebear-go/v10 and the avatar style definitions github.com/dicebear/styles/v10. The module path carries the major version, so import it with the /v10 suffix. sh go get github.com/dicebear/dicebear-go/v10 go get github.com/dicebear/styles/v10 text Usage We use the avatar style lorelei in our example. You can find more avatar styles here. Each style is exposed as a raw-JSON string (e.g. styles.Lorelei) that you pass to NewStyle. go package main import ( "fmt" dicebear "github.com/dicebear/dicebear-go/v10" "github.com/dicebear/styles/v10" ) func main() { style, err := dicebear.NewStyle([]byte(styles.Lorelei)) if err != nil { panic(err) } avatar, err := dicebear.NewAvatar(style, map[string]any{ "seed": "John", // ... other options }) if err != nil { panic(err) } svg := avatar.SVG() fmt.Println(svg) } text 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 creators. The avatar styles are licensed under different licenses that the creators can choose themselves. For a quick overview we have created a license overview for you. ::: Deterministic avatars The seed option is the key to generating deterministic avatars. The same seed always produces the same avatar: go avatar1, _ := dicebear.NewAvatar(style, map[string]any{"seed": "user-123"}) avatar2, _ := dicebear.NewAvatar(style, map[string]any{"seed": "user-123"}) // avatar1.SVG() == avatar2.SVG() text Types Style A validated, immutable wrapper around a style definition. Build it once with NewStyle (from the definition's JSON bytes), then reuse it when generating multiple avatars. go style, err := dicebear.NewStyle(definitionJSON) if err != nil { panic(err) } avatar1, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Alice"}) avatar2, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Bob"}) text Avatar The main type for generating avatars. NewAvatar takes a *Style and a map[string]any of options, and returns (*Avatar, error) (invalid options and circular color references surface as an error). A nil options map is treated as empty. go avatar, err := dicebear.NewAvatar(style, map[string]any{ // ... options }) text OptionsDescriptor Describes all valid options for a given style. Useful for building UIs or validating user input. go descriptor := dicebear.NewOptionsDescriptor(style).ToJSON() text Methods SVG() / String() Return type: string Returns the avatar as SVG in XML format. Avatar also implements fmt.Stringer, so it can be used directly in string contexts (fmt.Println, fmt.Sprintf). go avatar, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Alice"}) svg := avatar.SVG() // or svg = avatar.String() text JSON() Return type: []byte (JSON with keys svg and options), error Returns the SVG and the resolved options as JSON. go avatar, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Alice"}) result, _ := avatar.JSON() // result → {"svg":"<svg>...</svg>","options":{"flip":"none",...}} text The resolved options are also available directly as a map via avatar.ResolvedOptions(). DataURI() Return type: string Returns the avatar as data URI. go avatar, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Alice"}) dataURI := avatar.DataURI() // <img src="{dataURI}" alt="Avatar" /> text Core options These options are the same across every DiceBear core. See Core options for the full reference. Here are the options in Go syntax: go avatar, _ := dicebear.NewAvatar(style, map[string]any{ "seed": "Alice", "flip": "horizontal", // "none", "horizontal", "vertical", "both" "rotate": 10, // -360 to 360, or [min, max] range "scale": 0.9, // 0 to 10 (1 = original), or [min, max] range "borderRadius": 50, // 0-50 (50 = circle) "size": 128, "translateX": 0, // -1000 to 1000 (percent of canvas width) "translateY": 0, // -1000 to 1000 (percent of canvas height) "idRandomization": true, "title": "User Avatar", "fontFamily": "Arial", // or []string{"Arial", "Helvetica"} "fontWeight": 700, // 1-1000 "backgroundColor": []string{"#b6e3f4", "#c0aede"}, "backgroundColorFill": "solid", // "solid", "linear", "radial" }) text Dynamic component and color options also work the same way. See Dynamic component options for all available patterns. Examples Avatar with custom background go avatar, _ := dicebear.NewAvatar(style, map[string]any{ "seed": "Alice", "backgroundColor": []string{"#b6e3f4", "#c0aede", "#d1d4f9"}, }) text Fixed size avatar go style, _ := dicebear.NewStyle([]byte(styles.Bottts)) avatar, _ := dicebear.NewAvatar(style, map[string]any{ "seed": "robot-42", "size": 128, "borderRadius": 50, // circular avatar }) text Avatar with transformations go style, _ := dicebear.NewStyle([]byte(styles.Avataaars)) avatar, _ := dicebear.NewAvatar(style, map[string]any{ "seed": "Jane", "flip": "horizontal", "rotate": 10, "scale": 0.9, "translateY": 5, }) text Multiple avatars on the same page When rendering multiple avatars on the same page, use idRandomization to prevent SVG ID conflicts: go style, _ := dicebear.NewStyle([]byte(styles.Lorelei)) for _, seed := range []string{"alice", "bob", "charlie"} { avatar, _ := dicebear.NewAvatar(style, map[string]any{ "seed": seed, "idRandomization": true, }) fmt.Println(avatar.SVG()) } text Weighted variant selection go avatar, _ := dicebear.NewAvatar(style, map[string]any{ "seed": "Alice", "topVariant": map[string]any{"short01": 2, "short02": 2, "long01": 1}, }) text --- Apps/Docs/Pages/How To Use/Http Api/Index (apps/docs/pages/how-to-use/http-api/index.md) --- title: HTTP API – Generate SVG Avatars via URL description: > Free avatar API and profile picture API by DiceBear. Generate random user avatars and user placeholder images with a simple URL. No authentication required. --- <script setup> import BrowserPreview from '@theme/components/ui/UiBrowserPreview.vue'; import DocsGrid from '@theme/components/docs/DocsGrid.vue'; const fileFormats = [ { title: 'SVG', description: 'Recommended. Scales indefinitely, no size limit, higher rate limit.', badge: 'Recommended', }, { title: 'PNG', description: 'Max. 256 × 256 px. Lower rate limit.', }, { title: 'JPG', description: 'Max. 256 × 256 px. Lower rate limit.', }, { title: 'WebP', description: 'Max. 256 × 256 px. Lower rate limit.', }, { title: 'AVIF', description: 'Max. 256 × 256 px. Lower rate limit.', }, { title: 'JSON', description: 'Returns avatar metadata as JSON instead of an image.', }, ]; </script> HTTP API: generate SVG avatars via URL Our HTTP API is the simplest way to use DiceBear as a profile picture API or avatar placeholder API. No authentication is required. Usage Use the following address and replace <styleName> with your preferred avatar style. Style names are lowercase, with hyphens for multi-word styles, e.g. lorelei, pixel-art, adventurer-neutral. Every official avatar style is supported. https://api.dicebear.com/10.x/<styleName>/svg text A few examples <BrowserPreview url="https://api.dicebear.com/10.x/pixel-art/svg" /> <BrowserPreview url="https://api.dicebear.com/10.x/lorelei/svg" /> Generate a consistent avatar from a user ID Use a stable identifier as the seed and every user gets the same avatar on every visit. A user ID works well, and the same seed always returns the same image. That makes it a good default avatar for people who haven't uploaded a photo yet, since the picture stays the same across pages and sessions. https://api.dicebear.com/10.x/lorelei/svg?seed=user-8f3a2c text <BrowserPreview url="https://api.dicebear.com/10.x/lorelei/svg?seed=user-8f3a2c" /> If the seed contains spaces or other special characters, URL-encode it first. :::info We provide a large number of avatar styles from different creators. The avatar styles are licensed under different licenses that the creators can choose themselves. For a quick overview we have created a license overview for you. ::: Listing available styles To discover which avatar styles an instance supports, send a request to the version root. It returns the available style names as JSON, sorted alphabetically: https://api.dicebear.com/10.x text json { "styles": ["adventurer", "adventurer-neutral", "avataaars", "..."] } text ::: infoThis endpoint is available from version 10.x onwards. Earlier versions do not support listing styles. ::: Style definition and options Each style also exposes two metadata endpoints. They are handy for building tooling on top of the API, such as avatar editors: https://api.dicebear.com/10.x/<styleName>/definition.json https://api.dicebear.com/10.x/<styleName>/options.json text definition.json returns the raw style definition, the same JSON that is shipped with the style's npm package.options.json describes every option the style accepts as query parameter, including field types, allowed enum values, and value ranges. An excerpt for Pixel Art: json { "seed": { "type": "string" }, "flip": { "type": "enum", "values": ["none", "horizontal", "vertical", "both"], "list": true }, "backgroundColor": { "type": "color", "list": true }, "hairVariant": { "type": "enum", "values": ["long01", "long02", "...", "short24"], "list": true, "weighted": true }, "hairProbability": { "type": "number", "min": 0, "max": 100 } } text ::: infoThese endpoints are available from version 10.x onwards. On self-hosted instances they are disabled by default. See the self-hosting guide. ::: Options All core options (such as seed, flip, rotate, scale, borderRadius, backgroundColor, and tags) are available as query parameters. Style-specific options are listed on each avatar style page. For example: <BrowserPreview url="https://api.dicebear.com/10.x/pixel-art/svg?seed=John" /> <BrowserPreview url="https://api.dicebear.com/10.x/pixel-art/svg?seed=Jane" /> :::tip If you want to pass more options, you connect them with a & as usual with query strings. ::: ::: warning The options idRandomization, fontFamily, fontWeight, and title are not supported by our public HTTP API. You can enable them by hosting your own instance. ::: Array options Array values are separated by a comma. For example, the URL could look like this if you want to provide the PRNG with several hair styles in addition to the seed. Note that the avatar styles provide different options. In this example, we use the Pixel Art avatar style. <BrowserPreview url="https://api.dicebear.com/10.x/pixel-art/svg?seed=John&hairVariant=short01,short02,short03,short04,short05" /> <BrowserPreview url="https://api.dicebear.com/10.x/pixel-art/svg?seed=Jane&hairVariant=long01,long02,long03,long04,long05" /> The tags filter is an array too. Separate the tags with a comma and prefix a tag with ! to exclude it: https://api.dicebear.com/10.x/planets/svg?seed=John&tags=animation text Enum options Enum values are passed as strings. For example, the flip option accepts none, horizontal, vertical, or both: <BrowserPreview url="https://api.dicebear.com/10.x/lorelei/svg?flip=horizontal" /> <BrowserPreview url="https://api.dicebear.com/10.x/lorelei/svg?flip=none" /> File format <DocsGrid :items="fileFormats" /> PNG, JPG, WebP and AVIF use the Noto Sans font and currently supports the following subsets: cyrillic, cyrillic-ext, devanagari, greek, greek-ext, japanese, korean, latin, latin-ext, simplified-chinese, thai and vietnamese. <BrowserPreview url="https://api.dicebear.com/10.x/bottts/svg" /> <BrowserPreview url="https://api.dicebear.com/10.x/bottts/png" /> <BrowserPreview url="https://api.dicebear.com/10.x/bottts/jpg" /> <BrowserPreview url="https://api.dicebear.com/10.x/bottts/webp" /> <BrowserPreview url="https://api.dicebear.com/10.x/bottts/avif" /> Versioning You can set the version in the URL. Just replace the 10.x from the previous examples with the one you want. | Version | Status | End of Life | | ------- | ---------- | -------------- | | 10.x | Active | None | | 9.x | Active | None | | 8.x | Deprecated | April 30, 2028 | | 7.x | Deprecated | April 30, 2028 | | 6.x | Deprecated | April 30, 2028 | | 5.x | Deprecated | April 30, 2028 | ::: warning Versions 5.x to 8.x will reach End of Life on April 30, 2028. After that date, the HTTP API for these versions will be shut down and no longer available. Please upgrade to the latest version. See the announcement for details. ::: ::: info You can host the API yourself to keep using discontinued versions after their End of Life. ::: Self-hosted avatar API Need a private or commercial setup? You can host the Avatar API yourself for full control over availability, rate limits, and data privacy. Fair use & rate limits Our API is free to use for non-commercial purposes, but please use it responsibly. We reserve the right to block abusive users. We currently limit requests per second to 50 for SVG and 10 for PNG, JPG, WebP, and AVIF. Exceeding the limit returns HTTP 429 Too Many Requests. We reserve the right to change these limits at any time without notice. For commercial use or higher limits, please set up your own instance. We're happy to answer questions: open a discussion on GitHub. Changes and availability Please be aware that we reserve the right to update the API at any time. While we will do our best to maintain backwards compatibility, we cannot guarantee this. Even though we try to always return the same avatar, the design and especially the source code may change. Additionally, we cannot guarantee that the API will always be available. If you need consistent access to the API, we recommend setting up your own instance. --- Apps/Docs/Pages/How To Use/Js Library/Index (apps/docs/pages/how-to-use/js-library/index.md) --- title: JavaScript Avatar Library – Browser & Node.js description: > Use the DiceBear JavaScript avatar library to generate SVG profile pictures in the browser (vanilla JS), React, Vue, Angular, Svelte, and Node.js. TypeScript support included. --- JavaScript avatar library The library is written in TypeScript / JavaScript and can be used in the browser and also in Node.js (version 22 or higher). In other environments you may be interested in the PHP Library, the Python Library, the Rust Library, the Go Library, the Dart Library, 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 You need two packages: the core library @dicebear/core and the avatar style definitions @dicebear/styles. npm install @dicebear/core @dicebear/styles text Usage We use the avatar style lorelei in our example. You can find more avatar styles here. js import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); const avatar = new Avatar(style, { seed: 'John', // ... other options }); const svg = avatar.toString(); text Each avatar style comes with several options. You can find them on the details page of each avatar style. ::: tip If you'd like to integrate the library into a framework, check out our guides for Angular, React, React Native, Vue or Svelte. ::: :::info We provide a large number of avatar styles from different creators. The avatar styles are licensed under different licenses that the creators can choose themselves. For a quick overview we have created a license overview for you. ::: Deterministic avatars The seed option is the key to generating deterministic avatars. The same seed will always produce the same avatar, which is useful for user profiles: js import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); // These will always produce the same avatar const avatar1 = new Avatar(style, { seed: 'user-123' }); const avatar2 = new Avatar(style, { seed: 'user-123' }); avatar1.toString() === avatar2.toString(); // true text Classes Avatar The main class for generating avatars. Pass a Style instance and optional options. js import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); const avatar = new Avatar(style, { // [!code focus:3] // ... options }); text Style An immutable wrapper around a style definition. js import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); // [!code focus:4] const avatar1 = new Avatar(style, { seed: 'Alice' }); const avatar2 = new Avatar(style, { seed: 'Bob' }); text OptionsDescriptor Describes all valid options for a given style. Useful for building UIs or validating user input. See Access Style Options for details. Methods .toString() Return type: string Returns the avatar as SVG in XML format. js import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); const avatar = new Avatar(style, { // ... options }); const svg = avatar.toString(); // [!code focus] text .toJSON() Return type: { svg: string, options: StyleOptions } Returns an object with the SVG and the resolved options that were used to generate the avatar. js import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); const avatar = new Avatar(style, { seed: 'John', // ... other options }); const json = avatar.toJSON(); // [!code focus] // Example output: // { // svg: '<svg>...</svg>', // options: { // seed: 'John', // // ... resolved options // } // } text .toDataUri() Return type: string Returns the avatar as data uri. This is useful for embedding the avatar directly in HTML or CSS. js import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); const avatar = new Avatar(style, { seed: 'John', // ... other options }); const dataUri = avatar.toDataUri(); // [!code focus] // Use in HTML // <img src={dataUri} alt="Avatar" /> text Options Every DiceBear core understands the same options. The full reference, including the background, per-component, and per-color options, lives on the Core options page. The examples below show how to pass them in JavaScript. Examples Avatar with custom background js import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); const avatar = new Avatar(style, { seed: 'John', backgroundColor: ['#b6e3f4', '#c0aede', '#d1d4f9'], // ... other options }); text Fixed size avatar js import { Style, Avatar } from '@dicebear/core'; import bottts from '@dicebear/styles/bottts.json' with { type: 'json' }; const style = new Style(bottts); const avatar = new Avatar(style, { seed: 'robot-42', size: 128, borderRadius: 50, // circular avatar // ... other options }); text Avatar with transformations js import { Style, Avatar } from '@dicebear/core'; import avataaars from '@dicebear/styles/avataaars.json' with { type: 'json' }; const style = new Style(avataaars); const avatar = new Avatar(style, { seed: 'Jane', flip: 'horizontal', rotate: 10, scale: 0.9, translateY: 5, // ... other options }); text Multiple avatars on the same page When inlining multiple avatars into the same document (e.g. dropping the SVG markup into the page rather than using <img src={dataUri}>), use idRandomization to suffix each SVG's internal IDs and avoid <defs> / url(#…) collisions: js import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); const users = ['alice', 'bob', 'charlie']; const avatars = users.map((user) => new Avatar(style, { seed: user, idRandomization: true, // ... other options }).toString(), ); text The suffix is drawn from Math.random() (not from the DiceBear PRNG), so two avatars rendered with the same seed get different IDs. This also means the rendered SVG is no longer deterministic; only the visual output is. Skip idRandomization for snapshot tests, SSR/hydration, or anywhere you depend on identical markup. When you only embed avatars via <img> (data URI or HTTP API) the IDs live inside isolated documents and ID randomization is unnecessary. Weighted variant selection You can influence the PRNG to prefer certain variants by passing a weight map. Variants not listed in the map are excluded; weights of 0 exclude that variant unless every mapped variant has weight 0, in which case the PRNG falls back to an unweighted pick across them: js import { Style, Avatar } from '@dicebear/core'; import avataaars from '@dicebear/styles/avataaars.json' with { type: 'json' }; const style = new Style(avataaars); const avatar = new Avatar(style, { seed: 'John', topVariant: { short01: 2, short02: 2, long01: 1 }, // ... other options }); text Accessibility By default the generated <svg> element is aria-hidden="true", so assistive technology skips it. This is the right default for purely decorative avatars next to a username. When the avatar conveys identity on its own (e.g. it is the only thing in a link, or has no visible label), set the title option. The renderer emits role="img" aria-label="…" on the root element and a <title> child, so screen readers announce the value: js const avatar = new Avatar(style, { seed: 'Alice', title: 'Avatar for Alice', }); text If you embed the SVG inside an <img> (via toDataUri()), use the <img> element's alt attribute instead. The SVG's internal title is not read by assistive technology when the SVG is loaded as an image. TypeScript The library is fully typed. You can import types for better IDE support: ts import { Avatar, Style } from '@dicebear/core'; import type { StyleOptions, StyleDefinition } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); const avatar = new Avatar(style, { seed: 'John', backgroundColor: ['#b6e3f4'], // ... other options }); text When importing a style definition as JSON, TypeScript infers the literal types of the definition, providing autocomplete for component and color option names. Convert to other formats Need PNG, JPEG, or other formats? Check out the Converter package. --- Apps/Docs/Pages/How To Use/Js Library/Converter/Index (apps/docs/pages/how-to-use/js-library/converter/index.md) --- title: Converter – Convert SVG Avatars to PNG, JPEG & More description: > Learn how to use the DiceBear Converter library in your project to convert SVG to PNG or JPEG. Works in the browser and in Node.js! --- 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 text ::: tipYou 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. js import { toPng } from '@dicebear/converter'; import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; const style = new Style(lorelei); const avatar = new Avatar(style, { seed: 'Alice', // ... other options }); const png = toPng(avatar); const dataUri = await png.toDataUri(); text 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. js import { toPng } from '@dicebear/converter'; const svg = '<svg>...</svg>'; const png = toPng(svg, { // ... options }); text 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. js import { toJpeg } from '@dicebear/converter'; const svg = '<svg>...</svg>'; const jpeg = toJpeg(svg, { // ... options }); text 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. js import { toWebp } from '@dicebear/converter'; const svg = '<svg>...</svg>'; const webp = toWebp(svg, { // ... options }); text ::: warning 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. js import { toAvif } from '@dicebear/converter'; const svg = '<svg>...</svg>'; const avif = toAvif(svg, { // ... options }); text ::: warning 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. js import { toPng } from '@dicebear/converter'; const svg = '<svg>...</svg>'; const png = toPng(svg, { // ... options }); const dataUri = await png.toDataUri(); // [!code focus] // Use in HTML: <img src={dataUri} alt="Avatar" /> text .toArrayBuffer() Return type: Promise<ArrayBuffer> Converts the image to an ArrayBuffer. This is useful for saving files or sending binary data. js import { toPng } from '@dicebear/converter'; const svg = '<svg>...</svg>'; const png = toPng(svg, { // ... options }); const buffer = await png.toArrayBuffer(); // [!code focus] text 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 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. js import { toPng } from '@dicebear/converter'; const png = toPng(svg, { size: 128, }); text fonts <Badge type="warning" text="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. js import { toPng } from '@dicebear/converter'; const png = toPng(svg, { fonts: ['/path/to/custom-font.ttf'], }); text includeExif <Badge type="warning" text="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 converter extracts the avatar style title, source URL, creator name, license, and copyright notice from the SVG and embeds them as Exif fields. js import { toPng } from '@dicebear/converter'; const png = toPng(svg, { includeExif: true, }); text ::: warningThis uses an exiftool singleton which needs to be exited manually when your application terminates. See the exiftool-vendored documentation for more information. js import { exiftool } from 'exiftool-vendored'; // When your application exits: await exiftool.end(); text ::: Examples Convert DiceBear avatar to PNG js import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; import { toPng } from '@dicebear/converter'; const style = new Style(lorelei); const avatar = new Avatar(style, { seed: 'Alice', backgroundColor: ['#b6e3f4'], }); const png = toPng(avatar); const dataUri = await png.toDataUri(); // Use in browser document.querySelector('img').src = dataUri; text Save avatar to file (Node.js) js import { Style, Avatar } from '@dicebear/core'; import bottts from '@dicebear/styles/bottts.json' with { type: 'json' }; import { toPng } from '@dicebear/converter'; import { writeFile } from 'node:fs/promises'; const style = new Style(bottts); const avatar = new Avatar(style, { seed: 'robot-42', }); const png = toPng(avatar); const buffer = await png.toArrayBuffer(); await writeFile('avatar.png', Buffer.from(buffer)); text Convert with Exif metadata (Node.js) js import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; import { toPng } from '@dicebear/converter'; import { exiftool } from 'exiftool-vendored'; import { writeFile } from 'node:fs/promises'; const style = new Style(lorelei); const avatar = new Avatar(style, { seed: 'Alice', }); 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(); text Use with custom fonts (Node.js) js import { Style, Avatar } from '@dicebear/core'; import initials from '@dicebear/styles/initials.json' with { type: 'json' }; import { toPng } from '@dicebear/converter'; const style = new Style(initials); const avatar = new Avatar(style, { seed: 'Alice', }); const png = toPng(avatar, { fonts: ['/path/to/Roboto-Bold.ttf'], }); const dataUri = await png.toDataUri(); text Convert with a custom size js import { Style, Avatar } from '@dicebear/core'; import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' }; import { toPng } from '@dicebear/converter'; const style = new Style(lorelei); const avatar = new Avatar(style, { seed: 'Alice' }); const png = toPng(avatar, { size: 128 }); const dataUri = await png.toDataUri(); text Convert any SVG (without DiceBear) js 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();
text
TypeScript The library is fully typed:
ts 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(); text Rendering with resvg yourself toPng and the other conversion functions handle this for you. If you drive resvg directly instead, run the SVG through normalizeMaskType first: js import { normalizeMaskType } from '@dicebear/converter'; const svg = normalizeMaskType(avatar.toString()); text resvg reads mask-type only as a presentation attribute, not from a style declaration. Figma writes the declaration, so official avatar styles carry masks that resvg would otherwise treat as the luminance default and render as fully hidden. normalizeMaskType mirrors the value onto the attribute. If nothing needs fixing, you get your input back unchanged. When a mask does need fixing, the function re-emits the SVG from a parsed tree, so formatting details like quote style may change, while the rendered image stays the same. Browsers honor both forms, so this only matters when you rasterize. --- Apps/Docs/Pages/How To Use/Php Library/Index (apps/docs/pages/how-to-use/php-library/index.md) --- title: PHP Avatar Library description: > Use the DiceBear PHP library to generate SVG profile pictures on the server. PHP 8.2+ with an API identical to the JavaScript library. --- PHP avatar library The PHP library provides an API identical to the JavaScript library. It requires PHP 8.2 or higher. The same seed and style definition produce SVGs byte-identical to the JavaScript reference. Installation You need two packages: the core library dicebear/core and the avatar style definitions dicebear/styles. composer require dicebear/core dicebear/styles text Usage php <?php use Composer\InstalledVersions; use DiceBear\Style; use DiceBear\Avatar; $basePath = InstalledVersions::getInstallPath('dicebear/styles'); $style = Style::fromJson(file_get_contents($basePath . '/src/lorelei.json')); $avatar = new Avatar($style, [ 'seed' => 'Alice', // ... other options ]); $svg = (string) $avatar; text 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 creators. The avatar styles are licensed under different licenses that the creators can choose themselves. For a quick overview we have created a license overview for you. ::: Deterministic avatars The seed option is the key to generating deterministic avatars. The same seed will always produce the same avatar: php $avatar1 = new Avatar($style, ['seed' => 'user-123']); $avatar2 = new Avatar($style, ['seed' => 'user-123']); (string) $avatar1 === (string) $avatar2; // true text Classes Avatar The main class for generating avatars. Pass a Style instance and optional options. php use DiceBear\Avatar; $avatar = new Avatar($style, [ // ... options ]); text Style An immutable wrapper around a style definition. Reuse it when generating multiple avatars from the same style. php use DiceBear\Style; use DiceBear\Avatar; $style = new Style($definition); $avatar1 = new Avatar($style, ['seed' => 'Alice']); $avatar2 = new Avatar($style, ['seed' => 'Bob']); text OptionsDescriptor Describes all valid options for a given style. Useful for building UIs or validating user input. php use DiceBear\Style; use DiceBear\OptionsDescriptor; $descriptor = new OptionsDescriptor(new Style($definition)); $fields = $descriptor->toJSON(); text Methods __toString() / toString() Return type: string Returns the avatar as SVG in XML format. The __toString() magic method allows using the avatar directly in string contexts. php $avatar = new Avatar($style, ['seed' => 'Alice']); $svg = (string) $avatar; // or $svg = $avatar->toString(); text toJSON() Return type: array{svg: string, options: array} Returns an associative array with the SVG and the resolved options. php $avatar = new Avatar($style, ['seed' => 'Alice']); $json = $avatar->toJSON(); // $json['svg'] → '<svg>...</svg>' // $json['options'] → ['seed' => 'Alice', ...] text toDataUri() Return type: string Returns the avatar as data URI. php $avatar = new Avatar($style, ['seed' => 'Alice']); $dataUri = $avatar->toDataUri(); // <img src="<?= $dataUri ?>" alt="Avatar" /> text Core options These options are the same across every DiceBear core. See Core options for the full reference. Here are the options in PHP syntax: php $avatar = new Avatar($style, [ 'seed' => 'Alice', 'flip' => 'horizontal', // 'none', 'horizontal', 'vertical', 'both' 'rotate' => 10, // -360 to 360, or [min, max] range 'scale' => 0.9, // 0 to 10 (1 = original), or [min, max] range 'borderRadius' => 50, // 0-50 (50 = circle) 'size' => 128, 'translateX' => 0, // -1000 to 1000 (percent of canvas width) 'translateY' => 0, // -1000 to 1000 (percent of canvas height) 'idRandomization' => true, 'title' => 'User Avatar', 'fontFamily' => 'Arial', // or ['Arial', 'Helvetica'] 'fontWeight' => 700, // 1-1000 'backgroundColor' => ['#b6e3f4', '#c0aede'], 'backgroundColorFill' => 'solid', // 'solid', 'linear', 'radial' ]); text Dynamic component and color options also work the same way. See Dynamic component options for all available patterns. Examples Avatar with custom background php $avatar = new Avatar($style, [ 'seed' => 'Alice', 'backgroundColor' => ['#b6e3f4', '#c0aede', '#d1d4f9'], ]); text Fixed size avatar php $basePath = InstalledVersions::getInstallPath('dicebear/styles'); $style = Style::fromJson(file_get_contents($basePath . '/src/bottts.json')); $avatar = new Avatar($style, [ 'seed' => 'robot-42', 'size' => 128, 'borderRadius' => 50, // circular avatar ]); text Avatar with transformations php $basePath = InstalledVersions::getInstallPath('dicebear/styles'); $style = Style::fromJson(file_get_contents($basePath . '/src/avataaars.json')); $avatar = new Avatar($style, [ 'seed' => 'Jane', 'flip' => 'horizontal', 'rotate' => 10, 'scale' => 0.9, 'translateY' => 5, ]); text Multiple avatars on the same page When rendering multiple avatars on the same page, use idRandomization to prevent SVG ID conflicts: php $users = ['alice', 'bob', 'charlie']; $avatars = array_map(function (string $user) use ($style) { return (string) new Avatar($style, [ 'seed' => $user, 'idRandomization' => true, ]); }, $users); text Weighted variant selection php $avatar = new Avatar($style, [ 'seed' => 'Alice', 'topVariant' => ['short01' => 2, 'short02' => 2, 'long01' => 1], ]); text --- Apps/Docs/Pages/How To Use/Python Library/Index (apps/docs/pages/how-to-use/python-library/index.md) --- title: Python Avatar Library description: > Use the DiceBear Python library to generate SVG profile pictures on the server. Python 3.10+ with an API identical to the JavaScript, PHP, Rust, and Go libraries. --- Python avatar library The Python library provides an API identical to the JavaScript library. It requires Python 3.10 or higher. The same seed and style definition produce SVGs byte-identical to the JavaScript reference. Installation You need two packages: the core library dicebear-core and the avatar style definitions dicebear-styles. bash pip install dicebear-core dicebear-styles text Usage We use the avatar style lorelei in our example. You can find more avatar styles here. python from importlib.resources import files from dicebear import Avatar, Style style = Style.from_json( files("dicebear_styles").joinpath("lorelei.json").read_text("utf-8") ) avatar = Avatar(style, { "seed": "John", # ... other options }) svg = avatar.to_string() text 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 creators. The avatar styles are licensed under different licenses that the creators can choose themselves. For a quick overview we have created a license overview for you. ::: Deterministic avatars The seed option is the key to generating deterministic avatars. The same seed will always produce the same avatar: python avatar1 = Avatar(style, {"seed": "user-123"}) avatar2 = Avatar(style, {"seed": "user-123"}) avatar1.to_string() == avatar2.to_string() # True text Classes Avatar The main class for generating avatars. Pass a Style instance and optional options. python from dicebear import Avatar avatar = Avatar(style, { # ... options }) text Style An immutable wrapper around a style definition. Reuse it when generating multiple avatars from the same style. python from dicebear import Avatar, Style style = Style(definition) avatar1 = Avatar(style, {"seed": "Alice"}) avatar2 = Avatar(style, {"seed": "Bob"}) text OptionsDescriptor Describes all valid options for a given style. Useful for building UIs or validating user input. python from dicebear import OptionsDescriptor, Style descriptor = OptionsDescriptor(Style(definition)) fields = descriptor.to_json() text Methods to_string() / str(avatar) Return type: str Returns the avatar as SVG in XML format. The __str__ method allows using the avatar directly in string contexts. python avatar = Avatar(style, {"seed": "Alice"}) svg = avatar.to_string() or svg = str(avatar) text to_json() Return type: dict with keys svg and options Returns a dict with the SVG and the resolved options. python avatar = Avatar(style, {"seed": "Alice"}) result = avatar.to_json() result["svg"] → '<svg>...</svg>' result["options"] → {"seed": "Alice", ...} text to_data_uri() Return type: str Returns the avatar as data URI. python avatar = Avatar(style, {"seed": "Alice"}) data_uri = avatar.to_data_uri() <img src="{data_uri}" alt="Avatar" /> text Core options These options are the same across every DiceBear core. See Core options for the full reference. Here are the options in Python syntax: python avatar = Avatar(style, { "seed": "Alice", "flip": "horizontal", # "none", "horizontal", "vertical", "both" "rotate": 10, # -360 to 360, or [min, max] range "scale": 0.9, # 0 to 10 (1 = original), or [min, max] range "borderRadius": 50, # 0-50 (50 = circle) "size": 128, "translateX": 0, # -1000 to 1000 (percent of canvas width) "translateY": 0, # -1000 to 1000 (percent of canvas height) "idRandomization": True, "title": "User Avatar", "fontFamily": "Arial", # or ["Arial", "Helvetica"] "fontWeight": 700, # 1-1000 "backgroundColor": ["#b6e3f4", "#c0aede"], "backgroundColorFill": "solid", # "solid", "linear", "radial" }) text Dynamic component and color options also work the same way. See Dynamic component options for all available patterns. Examples Avatar with custom background python avatar = Avatar(style, { "seed": "Alice", "backgroundColor": ["#b6e3f4", "#c0aede", "#d1d4f9"], }) text Fixed size avatar python from importlib.resources import files from dicebear import Avatar, Style style = Style.from_json( files("dicebear_styles").joinpath("bottts.json").read_text("utf-8") ) avatar = Avatar(style, { "seed": "robot-42", "size": 128, "borderRadius": 50, # circular avatar }) text Avatar with transformations python from importlib.resources import files from dicebear import Avatar, Style style = Style.from_json( files("dicebear_styles").joinpath("avataaars.json").read_text("utf-8") ) avatar = Avatar(style, { "seed": "Jane", "flip": "horizontal", "rotate": 10, "scale": 0.9, "translateY": 5, }) text Multiple avatars on the same page When rendering multiple avatars on the same page, use idRandomization to prevent SVG ID conflicts: python from dicebear import Avatar, Style style = Style(definition) users = ["alice", "bob", "charlie"] avatars = [ Avatar(style, {"seed": user, "idRandomization": True}).to_string() for user in users ] text Weighted variant selection python avatar = Avatar(style, { "seed": "Alice", "topVariant": {"short01": 2, "short02": 2, "long01": 1}, }) text --- Apps/Docs/Pages/How To Use/Rust Library/Index (apps/docs/pages/how-to-use/rust-library/index.md) --- title: Rust Avatar Library description: > Use the DiceBear Rust library to generate SVG profile pictures on the server. Rust 1.80+ with an API identical to the JavaScript library. --- Rust avatar library The Rust library provides an API identical to the JavaScript library. It requires Rust 1.80 or higher. The same seed and style definition produce SVGs byte-identical to the JavaScript reference. Installation You need two crates: the core library dicebear-core and the avatar style definitions dicebear-styles (each style sits behind a feature of the same name). Options are passed as a serde_json::Value, so add serde_json too. sh cargo add dicebear-core serde_json cargo add dicebear-styles --features lorelei text Usage We use the avatar style lorelei in our example. You can find more avatar styles here. rust use dicebear_core::{Avatar, Style}; use serde_json::json; let style = Style::from_str(dicebear_styles::LORELEI)?; let avatar = Avatar::new(&style, json!({ "seed": "John", // ... other options }))?; let svg = avatar.to_svg(); text 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 creators. The avatar styles are licensed under different licenses that the creators can choose themselves. For a quick overview we have created a license overview for you. ::: Deterministic avatars The seed option is the key to generating deterministic avatars. The same seed always produces the same avatar: rust let avatar1 = Avatar::new(&style, json!({ "seed": "user-123" }))?; let avatar2 = Avatar::new(&style, json!({ "seed": "user-123" }))?; assert_eq!(avatar1.to_svg(), avatar2.to_svg()); text Types Style A validated, immutable wrapper around a style definition. Build it once with Style::from_str (from a JSON string) or Style::from_value (from a serde_json::Value), then reuse it when generating multiple avatars. rust use dicebear_core::{Avatar, Style}; use serde_json::json; let style = Style::from_str(definition_json)?; let avatar1 = Avatar::new(&style, json!({ "seed": "Alice" }))?; let avatar2 = Avatar::new(&style, json!({ "seed": "Bob" }))?; text Avatar The main type for generating avatars. Avatar::new takes a &Style and a serde_json::Value of options, and returns Result<Avatar, Error> (invalid options and circular color references surface as an Error). rust use dicebear_core::{Avatar, Style}; use serde_json::json; let avatar = Avatar::new(&style, json!({ // ... options }))?; text OptionsDescriptor Describes all valid options for a given style. Useful for building UIs or validating user input. rust use dicebear_core::{OptionsDescriptor, Style}; let descriptor = OptionsDescriptor::new(&style).to_json(); text Methods to_svg() / to_string() Return type: &str / String Returns the avatar as SVG in XML format. Avatar also implements Display, so it can be used directly in string contexts (format!, println!, .to_string()). rust let avatar = Avatar::new(&style, json!({ "seed": "Alice" }))?; let svg = avatar.to_svg(); // or let svg = avatar.to_string(); text to_json() Return type: serde_json::Value with keys svg and options Returns a value with the SVG and the resolved options. rust let avatar = Avatar::new(&style, json!({ "seed": "Alice" }))?; let result = avatar.to_json(); // result["svg"] → "<svg>...</svg>" // result["options"] → { "seed": "Alice", ... } text to_data_uri() Return type: String Returns the avatar as data URI. rust let avatar = Avatar::new(&style, json!({ "seed": "Alice" }))?; let data_uri = avatar.to_data_uri(); // <img src="{data_uri}" alt="Avatar" /> text Core options These options are the same across every DiceBear core. See Core options for the full reference. Here are the options in Rust syntax: rust let avatar = Avatar::new(&style, json!({ "seed": "Alice", "flip": "horizontal", // "none", "horizontal", "vertical", "both" "rotate": 10, // -360 to 360, or [min, max] range "scale": 0.9, // 0 to 10 (1 = original), or [min, max] range "borderRadius": 50, // 0-50 (50 = circle) "size": 128, "translateX": 0, // -1000 to 1000 (percent of canvas width) "translateY": 0, // -1000 to 1000 (percent of canvas height) "idRandomization": true, "title": "User Avatar", "fontFamily": "Arial", // or ["Arial", "Helvetica"] "fontWeight": 700, // 1-1000 "backgroundColor": ["#b6e3f4", "#c0aede"], "backgroundColorFill": "solid", // "solid", "linear", "radial" }))?; text Dynamic component and color options also work the same way. See Dynamic component options for all available patterns. Examples Avatar with custom background rust let avatar = Avatar::new(&style, json!({ "seed": "Alice", "backgroundColor": ["#b6e3f4", "#c0aede", "#d1d4f9"], }))?; text Fixed size avatar rust use dicebear_core::{Avatar, Style}; use serde_json::json; let style = Style::from_str(dicebear_styles::BOTTTS)?; let avatar = Avatar::new(&style, json!({ "seed": "robot-42", "size": 128, "borderRadius": 50, // circular avatar }))?; text Avatar with transformations rust use dicebear_core::{Avatar, Style}; use serde_json::json; let style = Style::from_str(dicebear_styles::AVATAAARS)?; let avatar = Avatar::new(&style, json!({ "seed": "Jane", "flip": "horizontal", "rotate": 10, "scale": 0.9, "translateY": 5, }))?; text Multiple avatars on the same page When rendering multiple avatars on the same page, use idRandomization to prevent SVG ID conflicts: rust let style = Style::from_str(dicebear_styles::LORELEI)?; let avatars: Vec<String> = ["alice", "bob", "charlie"] .iter() .map(|seed| { Avatar::new(&style, json!({ "seed": seed, "idRandomization": true })) .map(|a| a.to_svg().to_string()) }) .collect::<Result<_, _>>()?; text Weighted variant selection rust let avatar = Avatar::new(&style, json!({ "seed": "Alice", "topVariant": { "short01": 2, "short02": 2, "long01": 1 }, }))?;``
---
Apps/Docs/Pages/Introduction/Index (apps/docs/pages/introduction/index.md)
---
title: DiceBear – Open Source Avatar Library & API
description: >
DiceBear is a free, open source avatar library and avatar API. Generate
deterministic SVG profile pictures and user placeholder images via JavaScript
library, PHP library, Python library, Rust library, Go library, Dart library,
HTTP API, or CLI.
---
<script setup>
import { Palette, Code2, Globe, Terminal, Server, Library, Boxes, Hexagon, Target } from '@lucide/vue';
import DocsHighlights from '@theme/components/docs/DocsHighlights.vue';
const highlights = [
{
icon: Globe,
title: 'HTTP API',
description:
'Use a simple URL to embed avatars in any language or platform without installing anything.',
color: '#22c55e',
link: '/how-to-use/http-api/',
},
{
icon: Code2,
title: 'JS Library',
description:
'Generate avatars in the browser or Node.js with full TypeScript support. Great for React, Vue, Svelte, and more.',
color: '#1689cc',
link: '/how-to-use/js-library/',
},
{
icon: Server,
title: 'PHP Library',
description:
'Generate avatars on the server with PHP 8.2+. Identical API to the JS library: same seed, same result.',
color: '#8b5cf6',
link: '/how-to-use/php-library/',
},
{
icon: Library,
title: 'Python Library',
description:
'Generate avatars on the server with Python 3.10+. Identical API to the JS library: same seed, same result.',
color: '#3b82f6',
link: '/how-to-use/python-library/',
},
{
icon: Boxes,
title: 'Rust Library',
description:
'Generate avatars on the server with Rust 1.80+. Identical API to the JS library: same seed, same result.',
color: '#14b8a6',
link: '/how-to-use/rust-library/',
},
{
icon: Hexagon,
title: 'Go Library',
description:
'Generate avatars on the server with Go 1.23+. Identical API to the JS library: same seed, same result.',
color: '#00add8',
link: '/how-to-use/go-library/',
},
{
icon: Target,
title: 'Dart Library',
description:
'Generate avatars in Dart and Flutter apps with Dart 3.4+. Identical API to the JS library: same seed, same result.',
color: '#0175c2',
link: '/how-to-use/dart-library/',
},
{
icon: Terminal,
title: 'CLI',
description:
'Perfect for automations and batch exports in multiple image formats directly from the command line.',
color: '#f59e0b',
link: '/how-to-use/cli/',
},
{
icon: Palette,
title: 'Editor',
description:
'Use the interactive Editor to browse all avatar styles, customize options, and export avatars without writing any code.',
color: '#ec4899',
link: 'https://editor.dicebear.com',
},
];
</script>
DiceBear: open source avatar library & API
What is DiceBear?
DiceBear generates avatars for your project. The avatar styles cover a range of
looks, from abstract shapes to designed characters, and the avatars can be used
in many kinds of applications.
In addition to purely random avatars, you can also create
deterministic avatars
for user identities. With the built-in
PRNG you create
the same avatar over and over again based on a seed. Individual avatars are also
possible: each avatar style provides many options to adjust the result.
DiceBear is available through the JavaScript library,
PHP library,
Python library,
Rust library,
Go library,
Dart library, HTTP API,
CLI,
Figma plugin,
Editor and Playground, so you can
integrate it into most projects. The Avatar API
provides URL-based integration without installing anything.
How to use?
<DocsHighlights :highlights="highlights" />
How does it work?
The avatars are created in
SVG format. This
allows to generate avatars dynamically without much computing power. In most
cases, various SVG elements such as hair, eyes, ears etc. are selected from a
set and combined to create a character / avatar.
FNV-1a
combined with
Mulberry32
is used as the algorithm for the
PRNG. The PRNG
does not attempt to be
cryptographically secure.
Privacy by design
DiceBear is built with privacy in mind. When using the
JavaScript library,
PHP library,
Python library,
Rust library, Go library
or Dart library, avatars are generated entirely on
your infrastructure. No personal data ever leaves your systems. For teams that
require full control over data retention and infrastructure, DiceBear can be
self-hosted, so there is no dependency on
external services.
---
Apps/Docs/Pages/Legal/Legal Notice/Index (apps/docs/pages/legal/legal-notice/index.md)
---
title: Legal Notice
editLink: false
aside: false
sidebarMenuLabel: Language
---
---
Apps/Docs/Pages/Licenses/Index (apps/docs/pages/licenses/index.md)
---
editLink: false
aside: false
description:
The licenses of all DiceBear avatar styles and the MIT license of the DiceBear
software.
---
<script setup lang="ts">
import PageLicenses from '@theme/components/pages/PageLicenses.vue';
</script>
Licenses
While the DiceBear code is MIT licensed (see Software), each artist
chooses the license for their own avatar style. The overview below groups the
styles by license, with the artist, the source work, and the license linked for
each one.
<PageLicenses />
---
Apps/Docs/Pages/Playground/Index (apps/docs/pages/playground/index.md)
---
layout: page
title: Playground
editLink: false
aside: false
description: >
Free online avatar maker. Design custom profile pictures, preview avatar
styles, and get integration code for your project.
---
<script setup lang="ts">
import Playground from "@playground/Playground.vue";
</script>
<Playground />
---

README (README.md) Copy Section

One library, six languages Copy Chapter

Without writing code Copy Chapter

This repository Copy Chapter

License Copy Chapter

Star this repository Copy Chapter

Sponsors Copy Chapter

CHANGELOG (CHANGELOG.md) Copy Section

Changelog

[Unreleased] Copy Chapter

Added Copy Section

Fixed Copy Section

[10.5.0] - 2026-08-09 Copy Chapter

Added Copy Section

Changed Copy Section

Deprecated Copy Section

Fixed Copy Section

[10.4.0] - 2026-08-01 Copy Chapter

Changed Copy Section

[10.4.0-rc.2] - 2026-07-31 Copy Chapter

Fixed Copy Section

[10.4.0-rc.1] - 2026-07-31 Copy Chapter

Added Copy Section

Fixed Copy Section

[10.3.2] - 2026-07-29 Copy Chapter

Fixed Copy Section

Changed Copy Section

[10.3.1] - 2026-07-27 Copy Chapter

Fixed Copy Section

[10.3.0] - 2026-06-13 Copy Chapter

Added Copy Section

Deprecated Copy Section

[10.2.0] - 2026-06-10 Copy Chapter

Added Copy Section

Fixed Copy Section

[10.2.0-rc.1] - 2026-06-07 Copy Chapter

Added Copy Section

Fixed Copy Section

[10.1.0] - 2026-06-06 Copy Chapter

Changed Copy Section

[10.1.0-rc.1] - 2026-06-02 Copy Chapter

Added Copy Section

[10.0.2] - 2026-06-02 Copy Chapter

Fixed Copy Section

[10.0.1] - 2026-05-29 Copy Chapter

Fixed Copy Section

[10.0.0] - 2026-05-27 Copy Chapter

Added Copy Section

Changed Copy Section

Removed Copy Section

CONTRIBUTING (CONTRIBUTING.md) Copy Section

Contributing

Before you start Copy Chapter

Requirements Copy Chapter

Local setup Copy Chapter

Common scripts Copy Chapter

Repository layout Copy Chapter

Working on a package Copy Chapter

TypeScript packages (src/js/) )')" title="Copy section prompt for LLMs"> Copy Section

PHP core (src/php/core/) )')" title="Copy section prompt for LLMs"> Copy Section

Python core (src/python/core/) )')" title="Copy section prompt for LLMs"> Copy Section

Rust core (src/rust/core/) )')" title="Copy section prompt for LLMs"> Copy Section

Go core (src/go/core/) )')" title="Copy section prompt for LLMs"> Copy Section

Dart core (src/dart/core/) )')" title="Copy section prompt for LLMs"> Copy Section

Cross-language parity Copy Section

Documentation changes (apps/docs/) )')" title="Copy chapter prompt for LLMs"> Copy Chapter

Editor changes (apps/editor/) )')" title="Copy chapter prompt for LLMs"> Copy Chapter

Code style Copy Chapter

Releasing (maintainers only) Copy Chapter

Licensing Copy Chapter

Package.Json (package.json) Copy Section

Turbo.Json (turbo.json) Copy Section

Apps/Docs/README (apps/docs/README.md) Copy Section

dicebear.com

Contributing Copy Chapter

Apps/Docs/Package.Json (apps/docs/package.json) Copy Section

Apps/Docs/Tsconfig.Json (apps/docs/tsconfig.json) Copy Section

Apps/Docs/Turbo.Json (apps/docs/turbo.json) Copy Section

Apps/Docs/Pages/Index (apps/docs/pages/index.md) Copy Section

Apps/Docs/Pages/Animated Avatars/Index (apps/docs/pages/animated-avatars/index.md) Copy Section

README (README.md)

One library, six languages

Without writing code

This repository

License

Star this repository

Sponsors

CHANGELOG (CHANGELOG.md)

[Unreleased]

Added

Fixed

[10.5.0] - 2026-08-09

Added

Changed

Deprecated

Fixed

[10.4.0] - 2026-08-01

Changed

[10.4.0-rc.2] - 2026-07-31

Fixed

[10.4.0-rc.1] - 2026-07-31

Added

Fixed

[10.3.2] - 2026-07-29

Fixed

Changed

[10.3.1] - 2026-07-27

Fixed

[10.3.0] - 2026-06-13

Added

`Deprecated`

`[10.2.0] - 2026-06-10`

`Added`

`Fixed`

`[10.2.0-rc.1] - 2026-06-07`

`Added`

`Fixed`

`[10.1.0] - 2026-06-06`

`Changed`

`[10.1.0-rc.1] - 2026-06-02`

`Added`

`[10.0.2] - 2026-06-02`

`Fixed`

`[10.0.1] - 2026-05-29`

`Fixed`

`[10.0.0] - 2026-05-27`

`Added`

`Changed`

`Removed`

`CONTRIBUTING (CONTRIBUTING.md)`

`Contributing`

`Before you start`

`Requirements`

`Local setup`

`Common scripts`

`Repository layout`

`Working on a package`

`TypeScript packages (`src/js/`)`

`PHP core (`src/php/core/`)`

`Python core (`src/python/core/`)`

`Rust core (`src/rust/core/`)`

`Go core (`src/go/core/`)`

`Dart core (`src/dart/core/`)`

`Cross-language parity`

`Documentation changes (`apps/docs/`)`

`Editor changes (`apps/editor/`)`

`Code style`

`Releasing (maintainers only)`

`Licensing`

`Package.Json (package.json)`

`Turbo.Json (turbo.json)`

`Apps/Docs/README (apps/docs/README.md)`

`dicebear.com`

`Contributing`

`Apps/Docs/Package.Json (apps/docs/package.json)`

`Apps/Docs/Tsconfig.Json (apps/docs/tsconfig.json)`

`Apps/Docs/Turbo.Json (apps/docs/turbo.json)`

`Apps/Docs/Pages/Index (apps/docs/pages/index.md)`

`Apps/Docs/Pages/Animated Avatars/Index (apps/docs/pages/animated-avatars/index.md)`

`Apps/Docs/Pages/Guides/Access All Available Options/Index (apps/docs/pages/guides/access-all-available-options/index.md)`