README
¶
DiceBear Core (Go)
Go implementation of the DiceBear avatar library. Generates deterministic SVG avatars from style definitions and a seed string.
DiceBear is available for multiple languages. All implementations share the same PRNG and rendering pipeline, producing identical SVG output for the same seed, style, and options — regardless of the language used.
Installation
go get github.com/dicebear/dicebear-go/v10
Requires Go 1.23 or newer.
Usage
import (
dicebear "github.com/dicebear/dicebear-go/v10"
"github.com/dicebear/styles/v10"
)
// From a style definition (raw JSON, e.g. the pure-data styles module)
style, _ := dicebear.NewStyle([]byte(styles.Lorelei))
avatar, _ := dicebear.NewAvatar(style, map[string]any{
"seed": "John Doe",
"size": 128,
})
avatar.SVG() // SVG string
avatar.DataURI() // data:image/svg+xml;charset=utf-8,...
Using the Style type
style, _ := dicebear.NewStyle([]byte(styles.Lorelei))
// Create multiple avatars from the same style
avatar1, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Alice"})
avatar2, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Bob"})
Sponsors
Advertisement: Many thanks to our sponsors who provide us with free or discounted products.
Documentation
¶
Overview ¶
Package dicebear is the Go implementation of the DiceBear avatar library. It generates deterministic SVG avatars from a style definition and a seed string.
DiceBear is available for multiple languages (JavaScript, PHP, Python, Rust and Go). All implementations share the same key-based PRNG and rendering pipeline, producing byte-identical SVG output for the same seed, style, and options — verified against the cross-language parity fixtures under tests/fixtures/parity in the monorepo.
This package is a thin public façade: Avatar, Style, OptionsDescriptor and the typed errors (ValidationError, CircularColorReferenceError). The engine — PRNG, resolver, renderer, options reader, style model, validation — lives under internal/ so it can be refactored freely without affecting the public API. The color helpers are the one other public surface, in the sub-package github.com/dicebear/dicebear-go/v10/color.
Style definitions and option sets are the same JSON the npm, Composer, PyPI and crates.io packages consume; the pure-data style definitions ship as github.com/dicebear/styles/v10.
style, err := dicebear.NewStyle([]byte(styles.Adventurer))
if err != nil {
// handle error
}
avatar, err := dicebear.NewAvatar(style, map[string]any{
"seed": "John Doe",
"size": 128,
})
if err != nil {
// handle error
}
svg := avatar.SVG() // SVG string
uri := avatar.DataURI() // data:image/svg+xml;charset=utf-8,...
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Avatar ¶
type Avatar struct {
// contains filtered or unexported fields
}
Avatar is a rendered avatar. NewAvatar immediately resolves and renders the SVG; the accessor methods return different serializations of that result.
func NewAvatar ¶
NewAvatar validates options, then resolves and renders an avatar for style. A nil options map is treated as empty. Returns an error on invalid options or a circular color reference.
Options are normalized through a JSON round-trip, so passing map[string]any{"size": 128} (a Go int) behaves the same as the JSON 128.
func (*Avatar) JSON ¶
JSON returns { "svg", "options" } — the SVG and the resolved options used to render it — as JSON bytes.
It is built by hand rather than via json.Marshal for byte parity with the JS/PHP/Rust ports: those keep the resolved options in resolution order and do not HTML-escape the SVG, whereas json.Marshal would sort the map keys alphabetically and escape <, > and & in the embedded markup.
func (*Avatar) ResolvedOptions ¶
ResolvedOptions returns a deep copy of the fully resolved options used to render the avatar. The raw seed is deliberately excluded. The copy is deep (color slices are cloned) so a caller mutating the result cannot corrupt the avatar's internal state — matching the JS port's structuredClone.
type CircularColorReferenceError ¶
type CircularColorReferenceError = errs.CircularColorReferenceError
CircularColorReferenceError is returned when a color in the style definition references itself, directly or indirectly.
type OptionsDescriptor ¶
type OptionsDescriptor = style.OptionsDescriptor
OptionsDescriptor describes every option a given style accepts. Tooling such as the editor uses it to render form controls and validation hints.
func NewOptionsDescriptor ¶
func NewOptionsDescriptor(s *Style) *OptionsDescriptor
NewOptionsDescriptor returns a descriptor for the given style.
type Style ¶
Style is a validated, decomposed wrapper around a style definition. Build it once with NewStyle, then reuse it across many avatars.
type ValidationError ¶
type ValidationError = errs.ValidationError
ValidationError is returned when a style definition or an options object fails schema (or, for style definitions, alias) validation. It is an alias of the internal error type, so type assertions and errors.As work across the package boundary.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package color holds the color helpers used by the DiceBear renderer and the option resolver: hex normalization, WCAG relative luminance, contrast sorting, and exclusion filtering.
|
Package color holds the color helpers used by the DiceBear renderer and the option resolver: hex normalization, WCAG relative luminance, contrast sorting, and exclusion filtering. |
|
internal
|
|
|
errs
Package errs holds the error types that surface through the public API.
|
Package errs holds the error types that surface through the public API. |
|
initials
Package initials derives display initials from a seed string.
|
Package initials derives display initials from a seed string. |
|
num
Package num holds the numeric helpers shared by the PRNG and the renderer: SVG number formatting and the JavaScript-compatible half-up rounding the rest of the engine depends on for cross-language parity.
|
Package num holds the numeric helpers shared by the PRNG and the renderer: SVG number formatting and the JavaScript-compatible half-up rounding the rest of the engine depends on for cross-language parity. |
|
prng
Package prng is the key-based pseudorandom number generator and its primitives (FNV-1a, Mulberry32).
|
Package prng is the key-based pseudorandom number generator and its primitives (FNV-1a, Mulberry32). |
|
render
Package render resolves options against a style and turns the element tree into the final SVG.
|
Package render resolves options against a style and turns the element tree into the final SVG. |
|
style
Package style is the validated, decomposed model of a style definition: the element tree, components (with aliases flattened), colors, and metadata, plus the OptionsDescriptor that enumerates a style's accepted options.
|
Package style is the validated, decomposed model of a style definition: the element tree, components (with aliases flattened), colors, and metadata, plus the OptionsDescriptor that enumerates a style's accepted options. |
|
validate
Package validate checks style definitions and options against the shared draft-07 JSON schemas (the pure-data github.com/dicebear/schema module).
|
Package validate checks style definitions and options against the shared draft-07 JSON schemas (the pure-data github.com/dicebear/schema module). |