DiceBear 10.2 - Release Notes

[FlorianKoerner]

After Python joined the family in 10.1, version 10.2 adds two more official implementations: DiceBear now speaks Rust 🦀 and Go 🐹

The API is the same as in JavaScript, PHP and Python, and the same seed and style definition produce byte-identical SVGs in all five languages.

🦀 Rust Support

DiceBear is now available as a Rust crate (Rust 1.80+). You need two crates: the core library dicebear-core and the avatar style definitions dicebear-styles, where each style sits behind a feature of the same name.

• https://www.dicebear.com/how-to-use/rust-library/
• https://crates.io/crates/dicebear-core
• https://crates.io/crates/dicebear-styles

Example:

cargo add dicebear-core serde_json
cargo add dicebear-styles --features lorelei

use dicebear_core::{Avatar, Style};
use serde_json::json;

let style = Style::from_str(dicebear_styles::LORELEI)?;

let avatar = Avatar::new(&style, json!({
    "seed": "Felix",
    // ... other options
}))?;

let svg = avatar.to_svg();

🐹 Go Support

DiceBear is also available as a Go module (Go 1.23+). Again you need two packages: the core library github.com/dicebear/dicebear-go/v10 and the avatar style definitions github.com/dicebear/styles/v10. The module paths carry the major version, so both are imported with the /v10 suffix.

• https://www.dicebear.com/how-to-use/go-library/
• https://pkg.go.dev/github.com/dicebear/dicebear-go/v10
• https://pkg.go.dev/github.com/dicebear/styles/v10

Example:

go get github.com/dicebear/dicebear-go/v10
go get github.com/dicebear/styles/v10

import (
	dicebear "github.com/dicebear/dicebear-go/v10"
	"github.com/dicebear/styles/v10"
)

style, err := dicebear.NewStyle([]byte(styles.Lorelei))

avatar, err := dicebear.NewAvatar(style, map[string]any{
	"seed": "Felix",
	// ... other options
})

svg := avatar.SVG()

🔍 How do we keep five languages byte-identical?

With five implementations generating the same avatars, a fair question is how we make sure that seed: "Felix" looks exactly the same everywhere.

The first part of the answer: no implementation makes its own decisions. Every library uses the same deterministic random number generator and the same rendering pipeline. Your seed is turned into a number, and that number drives every "random" choice (which hairstyle, which color) in a fixed order. The JavaScript library is the reference, and the other languages follow it step by step.

The second part is a shared test suite. From the JavaScript reference we generate fixture files with a few hundred test cases: expected SVGs for many seed and option combinations, expected random number sequences, color calculations, initials for tricky names, and which style definitions and option values must be rejected as invalid. Every implementation has to reproduce these fixtures byte for byte in CI. If a single character differs, the build fails.

This is harder than it sounds, because programming languages disagree on surprisingly small things, like how to round -0.5 or the last decimal of a pow() call. Whenever the test suite catches such a difference, we pin down one behavior and make every language follow it. A few of those fixes landed in this release:

• Color luminance is now computed from a precomputed lookup table instead of calling pow() at runtime. Math libraries round pow() slightly differently (even browsers disagree among themselves), which in contrived cases could change contrast-based color ordering. JavaScript output is unchanged, and rendered SVGs were never affected.
• Initials with an @ in the seed (e.g. an email address) now discard everything from the @ onward in all languages, even when the seed contains line breaks.
• When initials start with a character outside the Basic Multilingual Plane, such as an emoji, the JavaScript library no longer emits a lone UTF-16 surrogate (ill-formed XML). All languages now agree.
• PHP data URIs are now percent-encoded exactly like JavaScript's encodeURIComponent, so toDataUri() is byte-identical across languages.
• The resolved-options JSON returned by toJson() is now serialized identically everywhere: Rust orders size before title like the others, and Python emits whole numbers as 1 instead of 1.0.

💬 Which language next?

DiceBear now speaks five languages, and we'd like to hand the choice of the sixth to you. Ruby, Java, C#, Swift, or something else entirely? Head over to the discussions and tell us which official implementation you want to see next.

---

This discussion was created from the release DiceBear 10.2 - Release Notes.