Rust avatar library

Generate avatars natively in Rust (1.80 or higher), with no external service involved. The API mirrors the JavaScript library, and the output is byte-identical: the same seed and style produce the same SVG in every DiceBear library.

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.

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

Usage

We use the avatar style lorelei in our example. You can find more avatar styles here.

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();

Each avatar style comes with several options. You can find them on the details page of each avatar style.

INFO

The avatar styles come from many creators, and each creator chooses the license for their own style. The license overview lists them all in one place.

Deterministic avatars

The seed option is the key to generating deterministic avatars. The same seed always produces the same avatar:

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());

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.

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" }))?;

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

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

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

OptionsDescriptor

Describes all valid options for a given style. Useful for building UIs or validating user input.

use dicebear_core::{OptionsDescriptor, Style};

let descriptor = OptionsDescriptor::new(&style).to_json();

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()).

let avatar = Avatar::new(&style, json!({ "seed": "Alice" }))?;

let svg = avatar.to_svg();
// or
let svg = avatar.to_string();

to_json()

Return type: serde_json::Value with keys svg and options

Returns a value with the SVG and the resolved options.

let avatar = Avatar::new(&style, json!({ "seed": "Alice" }))?;

let result = avatar.to_json();

// result["svg"]     → "<svg>...</svg>"
// result["options"] → { "seed": "Alice", ... }

to_data_uri()

Return type: String

Returns the avatar as data URI.

let avatar = Avatar::new(&style, json!({ "seed": "Alice" }))?;

let data_uri = avatar.to_data_uri();

// <img src="{data_uri}" alt="Avatar" />

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:

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"
}))?;

Dynamic component and color options also work the same way. See Dynamic component options for all available patterns.

Examples

Avatar with custom background

let avatar = Avatar::new(&style, json!({
    "seed": "Alice",
    "backgroundColor": ["#b6e3f4", "#c0aede", "#d1d4f9"],
}))?;

Fixed size avatar

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
}))?;

Avatar with transformations

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,
}))?;

Multiple avatars on the same page

When rendering multiple avatars on the same page, use idRandomization to prevent SVG ID conflicts:

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<_, _>>()?;

Weighted variant selection

let avatar = Avatar::new(&style, json!({
    "seed": "Alice",
    "topVariant": { "short01": 2, "short02": 2, "long01": 1 },
}))?;