dicebear--dicebear/apps/docs/pages/how-to-use/rust-library/index.md

title, description

title	description
Rust Avatar Library	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.

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

We provide a large number of avatar styles from different artists. The avatar styles are licensed under different licenses that the artists can choose themselves. For a quick overview we have created an license overview for you.

:::

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

The core options are identical to the JavaScript library. See the JS Library 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 the JS Library documentation 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 },
}))?;