@dicebear/core

@dicebear/core is the rendering engine behind DiceBear, an open-source avatar library that turns any seed string (a username, email, or user ID) into a reproducible SVG avatar. The same seed always produces the same avatar, so applications can store a short string instead of an uploaded image while still giving every user a distinct, recognizable identicon.

Core itself is style-agnostic: avatar styles (35+, covering illustrated characters, geometric identicons, pixel art, and more) live as separate JSON style definitions from the @dicebear/collection package or dicebear/styles repo, and Core’s Avatar class combines a style definition with seed and options to produce SVG output (toString(), toDataUri()). The same core+style architecture is reimplemented natively in PHP, Python, Rust, Go, and Dart, all producing byte-identical SVG output to the JavaScript reference.

What You Get

• An Avatar class that combines a style definition, seed, and options into rendered SVG output
• toString() and toDataUri() output methods for embedding avatars directly in HTML or CSS
• A style-agnostic core so any of the 35+ @dicebear/collection styles (or a custom Figma-authored style) can be rendered through the same API
• Deterministic seeding via a built-in PRNG, guaranteeing the same seed always renders the same avatar
• Shared architecture across six language ports (JS/TS, PHP, Python, Rust, Go, Dart) verified against a common test suite for byte-identical SVG output

Common Use Cases

• Generating default profile-picture avatars for new user signups without requiring an image upload
• Rendering consistent avatars server-side (PHP, Python, Go, Rust) and client-side (JS) from the same seed for cross-platform apps
• Building a self-hosted avatar HTTP API or CLI tool on top of Core for bulk avatar generation
• Embedding customizable, brand-consistent placeholder avatars in dashboards, chat apps, or admin panels

Under The Hood

Architecture - Avatar.ts is the central class, composing a StyleDefinition, a seeded Prng, an OptionsDescriptor/Options validation layer, and a Renderer that walks the style definition to produce SVG output; a Resolver.ts and Style.ts mediate between the generic core and style-specific JSON definitions supplied by @dicebear/collection or custom Figma-exported styles. This separation is what lets one core renderer support 35+ visually distinct avatar styles without style-specific code living in the core package.

Tech Stack - TypeScript/Node (requires Node >=22), compiled via tsc with @tsconfig/recommended, validated against JSON Schema via ajv and the sibling @dicebear/schema package, and built as an ESM-only package ("type": "module"). The monorepo is a Turborepo (turbo.json) workspace containing parallel implementations in PHP, Python, Rust, Go, and Dart under src/, each targeting output parity with the JS reference.

Code Quality - Uses Node’s built-in test runner (node --test) rather than a third-party framework, keeping the dev dependency surface minimal; a tests/ directory alongside src/ exercises the Avatar/Resolver/Style pipeline. The project maintains a cross-language shared test suite (per the root README) that requires byte-identical SVG output across all six ports, which is an unusually strict quality bar for a monorepo spanning that many ecosystems.

API Design - The public API is deliberately small: construct new Avatar(definition, options), then call .toString() or .toDataUri() — most of the complexity (35+ styles, per-style options) lives in the style definitions rather than the core API surface, keeping onboarding fast. The same three-call shape (import, construct, .toString()) is mirrored across all six language ports per the README’s code sample, which lowers the learning curve for teams working across multiple backend languages.