dicebear 4.0.0b1

This beta introduces a fully typed, IDE-friendly API for style customisation, built on the same JSON-driven architecture DiceBear v10 uses internally. All existing code continues to work unchanged.

---

What's new

Typed style classes

Each avatar style now has its own Python dataclass with typed, documented fields. No more passing an untyped custom dict and guessing option names — your IDE will autocomplete them, and invalid usage is caught at construction time before any HTTP call is made.

from dicebear import DAvatar, DOptions, DColor
from dicebear.styles.adventurer import Adventurer

# Default avatar — pass the class directly
avatar = DAvatar(Adventurer, "john doe")

# Customised avatar — pass an instance
avatar = DAvatar(
    Adventurer(eyes=["variant01"], hair=["long01"], hairColor=DColor("b9a05f")),
    "john doe",
    options=DOptions(flip=True),
)

Without type-hinting

When you need to step outside the typed system (e.g. to pass an undocumented option), convert a style instance to a plain dict and extend it:

custom = {**Adventurer(eyes=["variant01"]).to_dict(), "someParam": "value"}
avatar = DAvatar("adventurer", "john doe", custom=custom)

JSON-driven code generation

Style classes are generated from the official dicebear/styles (https://github.com/dicebear/styles) JSON definitions — not hand-written. A workflow_dispatch CI action fetches the latest schemas and regenerates all files, keeping the library in sync with upstream automatically.

6 new styles

Styles now match the full dicebear/styles repo (37 total). New additions: Disco, Glyphs, Initial Face, Shape Grid, Stripes, Triangles.

---

Backwards compatibility

All v3.x code continues to work without any changes:

# This still works exactly as before
DAvatar(DStyle.adventurer, "john doe", custom={"eyes": "variant01"})

---

Breaking changes

None. This release is purely additive.

---

Upgrading

pip install dicebear==4.0.0b1

---

Caution

Beta notice — the typed style classes API is new. Field names are derived directly from the upstream JSON definitions and may shift if DiceBear updates their schemas before 4.0.0 stable. Python classes are automatically generated from these JSON definitions, so they may be inaccurate during this beta phase.

Please report any issues.