C# avatar library

Generate avatars in C#, from web backends to games. The library targets netstandard2.0 and net8.0, so it runs on .NET 8 and newer and on .NET Framework 4.6.1 and newer. 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.

Game engines have their own guides. In Godot the library runs only on a .NET build of the engine. Unity ships neither a NuGet client nor a runtime SVG renderer, so you have to add both yourself.

Installation

You need two packages: the core library DiceBear.Core and the avatar style definitions DiceBear.Styles.

dotnet add package DiceBear.Core
dotnet add package DiceBear.Styles

The styles package embeds every style in the assembly. Like the Go module there is no per-style opt-in, so a project that ships it carries the whole collection. Where that matters, skip the package and load the one definition you need from a file.

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 hand to Style.Parse.

using System.Text.Json.Nodes;
using DiceBear;

var style = Style.Parse(Styles.Lorelei);

var avatar = new Avatar(style, new JsonObject
{
    ["seed"] = "John",
    // ... other options
});

Console.WriteLine(avatar.ToSvg());

Style.Parse decodes and validates the raw JSON string. If you already hold a decoded definition as a JsonNode, pass it to the Style constructor instead.

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:

var first = new Avatar(style, new JsonObject { ["seed"] = "user-123" });
var second = new Avatar(style, new JsonObject { ["seed"] = "user-123" });

// first.ToSvg() == second.ToSvg()

Types

Style

A validated, immutable wrapper around a style definition. Build it once from the definition JSON, then reuse it when generating multiple avatars. Invalid definitions throw a StyleValidationException.

var style = Style.Parse(Styles.Lorelei);

var alice = new Avatar(style, new JsonObject { ["seed"] = "Alice" });
var bob = new Avatar(style, new JsonObject { ["seed"] = "Bob" });

Avatar

The main class for generating avatars. The constructor takes a Style and an optional JsonObject of options. Invalid options throw an OptionsValidationException, circular color references a CircularColorReferenceException. Omitting the options is the same as passing an empty object.

var avatar = new Avatar(style, new JsonObject
{
    // ... options
});

Avatar.FromJson(style, optionsJson) takes the options as raw JSON text, which is convenient when they arrive from a request body or a config file.

OptionsDescriptor

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

var descriptor = new OptionsDescriptor(style).ToJson();

Methods

ToSvg() / 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 interpolation.

var avatar = new Avatar(style, new JsonObject { ["seed"] = "Alice" });

var svg = avatar.ToSvg();
// or
svg = avatar.ToString();

ToJson()

Return type: string (a JSON object with the keys svg and options)

Returns the SVG and the resolved options as JSON text.

var avatar = new Avatar(style, new JsonObject { ["seed"] = "Alice" });

var result = avatar.ToJson();

// result → {"svg":"<svg>...</svg>","options":{"flip":"none",...}}

The resolved options are also available directly as a JsonObject via avatar.ResolvedOptions().

ToDataUri()

Return type: string

Returns the avatar as data URI.

var avatar = new Avatar(style, new JsonObject { ["seed"] = "Alice" });

var dataUri = avatar.ToDataUri();

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

Errors

Invalid input throws instead of returning a result type, which is what a .NET caller expects. The other language libraries name these types ValidationError after their own conventions.

Exception	Thrown when
StyleValidationException	A style definition violates the schema
OptionsValidationException	The options violate the schema
CircularColorReferenceException	A color in the definition references itself

Both validation exceptions carry the individual field failures in Details, each with the failing JSON pointer and the schema keyword that rejected it.

Core options

These options are the same across every DiceBear core. See Core options for the full reference. Here are the options in C# syntax:

var avatar = new Avatar(style, new JsonObject
{
    ["seed"] = "Alice",
    ["flip"] = "horizontal", // "none", "horizontal", "vertical", "both"
    ["rotate"] = 10, // -360 to 360, or a [min, max] range
    ["scale"] = 0.9, // 0 to 10 (1 = original), or a [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 new JsonArray("Arial", "Helvetica")
    ["fontWeight"] = 700, // 1-1000
    ["backgroundColor"] = new JsonArray("#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

Rendering in ASP.NET Core

An endpoint that returns the SVG directly:

app.MapGet("/avatar/{seed}", (string seed) =>
{
    var avatar = new Avatar(style, new JsonObject { ["seed"] = seed });

    return Results.Content(avatar.ToSvg(), "image/svg+xml");
});

Build the Style once at startup and keep it in a field or a singleton service. Validating and decomposing a definition is the expensive part, while rendering an avatar from an existing Style is cheap.

Avatar with custom background

var avatar = new Avatar(style, new JsonObject
{
    ["seed"] = "Alice",
    ["backgroundColor"] = new JsonArray("#b6e3f4", "#c0aede", "#d1d4f9"),
});

Fixed size avatar

var style = Style.Parse(Styles.Bottts);

var avatar = new Avatar(style, new JsonObject
{
    ["seed"] = "robot-42",
    ["size"] = 128,
    ["borderRadius"] = 50, // circular avatar
});

Avatar with transformations

var style = Style.Parse(Styles.Avataaars);

var avatar = new Avatar(style, new JsonObject
{
    ["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:

foreach (var seed in new[] { "alice", "bob", "charlie" })
{
    var avatar = new Avatar(style, new JsonObject
    {
        ["seed"] = seed,
        ["idRandomization"] = true,
    });

    Console.WriteLine(avatar.ToSvg());
}

Weighted variant selection

A weighted object makes some variants more likely than others. The lorelei style selects happy01 or happy02 mouths twice as often as sad01 here:

var avatar = new Avatar(style, new JsonObject
{
    ["seed"] = "Alice",
    ["mouthVariant"] = new JsonObject
    {
        ["happy01"] = 2,
        ["happy02"] = 2,
        ["sad01"] = 1,
    },
});