dice_bear
Flutter Package

A fully-typed Dart/Flutter wrapper for the DiceBear API (v9.x) that generates unique avatar profile pictures with extensive customization options.

DiceBear is an avatar library for designers and developers. Generate random, deterministic avatar profile pictures from seeds, supporting 30+ unique art styles with fine-grained style-specific customization.

GitHub stars pub package

Features

✨ Full Type Safety — Every style option is a dedicated Dart class with compile-time validation

🎯 30+ Avatar Styles — Support for all DiceBear styles including Adventurer, Avataaars, PixelArt, and more

🔧 Style-Specific Customization — Each style has its own set of customization options (eyes, mouth, accessories, etc.)

📦 Flexible Output — Get SVG URLs, rendered Flutter widgets, or raw SVG bytes

🎲 Deterministic & Random — Generate consistent avatars from a seed or random ones each time

Installation

Add to your pubspec.yaml:

dependencies:
  dice_bear: ^1.0.0

Then run flutter pub get.

Quick Start

Basic Usage

import 'package:dice_bear/dice_bear.dart';

// Create a simple avatar
final avatar = DiceBearBuilder(
  seed: 'john_doe',  // Deterministic: same seed = same avatar
  sprite: DiceBearSprite.adventurer,
).build();

// Render as Flutter widget
Widget widget = avatar.toImage(width: 200, height: 200);

// Get the SVG URL
Uri svgUrl = avatar.svgUri;

// Get raw SVG bytes
Uint8List? svgBytes = await avatar.asRawSvgBytes();

Random Avatar

// Generate a new random avatar each time
final avatar = DiceBearBuilder.withRandomSeed().build();

Advanced Usage

Style-Specific Customization

Each DiceBear style has its own options class for fine-grained control:

// Adventurer style with custom eye and mouth options
final avatar = DiceBearBuilder(
  seed: 'user123',
  sprite: DiceBearSprite.adventurer,
  styleOptions: DiceBearAdventurerOptions(
    eyes: ['variant01', 'variant05'],
    mouth: ['variant10'],
    glasses: ['variant02'],
    glassesProbability: 50,  // 50% chance of glasses
  ),
).build();

PixelArt with Customization

final avatar = DiceBearBuilder(
  seed: 'pixel_user',
  sprite: DiceBearSprite.pixelArt,
  styleOptions: DiceBearPixelArtOptions(
    accessories: ['variant01', 'variant02'],
    beard: ['variant03'],
    clothingColor: ['ff5733', 'fbf5e6'],
    eyesColor: ['647b90'],
  ),
).build();

Common Customization Parameters

Parameter Type Example Notes
backgroundColor Color? Color(0xFF3ECAF5) Applied to SVG background
radius int 10 Border radius (0-20)
scale int 100 Scale factor (0-200)
rotate int 45 Rotation in degrees (0-360)
flip bool true Flip horizontally
translateX, translateY int 10, -5 Translation offsets (-100 to 100)
size int 256 SVG size in pixels

Available Styles

Character-Based Styles (with eyes & mouth customization)

  • Adventurer / Adventurer Neutral — D&D-inspired characters
  • Avataaars / Avataaars Neutral — Cartoonish avatars
  • Big Ears / Big Ears Neutral — Quirky big-eared characters
  • Big Smile — Always happy expressions
  • Bottts / Bottts Neutral — Robot-like avatars
  • Croodles / Croodles Neutral — Minimalist faces
  • Fun Emoji — Expressive emoji style
  • Lorelei / Lorelei Neutral — Artistic character design
  • Micah — Stylized character portraits
  • Miniavs — Tiny avatar style
  • Personas — Professional-looking character avatars
  • Pixel Art / Pixel Art Neutral — 8-bit style avatars
  • Thumbs — Thumbs-up styled avatars
  • Toon Head — Cartoon character avatars

Geometric & Abstract Styles

  • Dylan — Gradient-based geometric design
  • Glass — Glassy geometric patterns
  • Icons — Icon-based avatars
  • Identicon — Hash-based geometric avatars
  • Initials — Two-letter initials display
  • Notionists / Notionists Neutral — Notion-inspired design
  • Open Peeps — Open-source character art
  • Rings — Concentric ring patterns
  • Shapes — Geometric shape arrangements

Widget Parameters

When calling .toImage(), you can pass additional Flutter parameters:

widget = avatar.toImage(
  width: 200,
  height: 200,
  fit: BoxFit.contain,
  alignment: Alignment.center,
  placeholderBuilder: (context) => CircularProgressIndicator(),
  semanticsLabel: 'User avatar for John Doe',
);
Parameter Type Default
width double? —
height double? —
fit BoxFit BoxFit.contain
alignment Alignment Alignment.center
placeholderBuilder WidgetBuilder? —
color Color? —
semanticsLabel String? —
clipBehavior Clip Clip.hardEdge
theme SvgTheme? —

Architecture

The library maintains a clean, semantically organized structure:

lib/
├── dice_bear.dart (main entry point)
└── src/
    └── style_options/
        ├── character_style_options.dart (abstract base)
        ├── adventurer_options.dart
        ├── avataaars_options.dart
        ├── big_ears_options.dart
        ├── big_smile_options.dart
        ├── bottts_options.dart
        ├── pixel_art_options.dart
        ├── persons_options.dart
        ├── rings_options.dart
        ├── shapes_options.dart
        └── ... (30 style option classes total)

Design Pattern

  • Abstract Base Class: DiceBearCharacterStyleOptions for humanoid styles with eyes and mouth fields
  • Standalone Implementations: Geometric and abstract styles directly implement DiceBearStyleOptions
  • Validation: Each style class validates its options before sending to the API
  • Composability: Mix and match styles with global and style-specific options

Minimum SDK

Requires Dart SDK >= 2.17.0 (supports super parameters syntax for cleaner inheritance)

Examples

Profile Picture Builder

class UserAvatar extends StatelessWidget {
  final String userId;
  final double size;
  
  const UserAvatar({
    required this.userId,
    this.size = 100,
  });
  
  @override
  Widget build(BuildContext context) {
    final avatar = DiceBearBuilder(
      seed: userId,
      sprite: DiceBearSprite.avataaars,
      backgroundColor: Colors.blue.shade100,
    ).build();
    
    return avatar.toImage(width: size, height: size);
  }
}

ListView.builder(
  itemCount: 10,
  itemBuilder: (context, index) {
    final avatar = DiceBearBuilder.withRandomSeed().build();
    return avatar.toImage(width: 100, height: 100);
  },
)

Testing

The package includes comprehensive unit tests covering all style options and API interactions.

flutter test

License

This package is licensed under the MIT License. See LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a pull request to the repository.

Support

Found an issue? Have a feature request? Open an issue on GitHub.

Libraries

dice_bear