Go avatar library

Generate avatars right in your Go services (1.23 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 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.

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

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.

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

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:

avatar1, _ := dicebear.NewAvatar(style, map[string]any{"seed": "user-123"})
avatar2, _ := dicebear.NewAvatar(style, map[string]any{"seed": "user-123"})

// avatar1.SVG() == avatar2.SVG()

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.

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

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.

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

OptionsDescriptor

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

descriptor := dicebear.NewOptionsDescriptor(style).ToJSON()

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

avatar, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Alice"})

svg := avatar.SVG()
// or
svg = avatar.String()

JSON()

Return type: []byte (JSON with keys svg and options), error

Returns the SVG and the resolved options as JSON.

avatar, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Alice"})

result, _ := avatar.JSON()

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

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

DataURI()

Return type: string

Returns the avatar as data URI.

avatar, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Alice"})

dataURI := avatar.DataURI()

// <img src="{dataURI}" 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 Go syntax:

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

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

Examples

Avatar with custom background

avatar, _ := dicebear.NewAvatar(style, map[string]any{
	"seed":            "Alice",
	"backgroundColor": []string{"#b6e3f4", "#c0aede", "#d1d4f9"},
})

Fixed size avatar

style, _ := dicebear.NewStyle([]byte(styles.Bottts))

avatar, _ := dicebear.NewAvatar(style, map[string]any{
	"seed":         "robot-42",
	"size":         128,
	"borderRadius": 50, // circular avatar
})

Avatar with transformations

style, _ := dicebear.NewStyle([]byte(styles.Avataaars))

avatar, _ := dicebear.NewAvatar(style, map[string]any{
	"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:

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

Weighted variant selection

avatar, _ := dicebear.NewAvatar(style, map[string]any{
	"seed":     "Alice",
	"topVariant": map[string]any{"short01": 2, "short02": 2, "long01": 1},
})