beanheads 0.2.0

A customizable cartoon avatar generator that produces SVG strings. Dart port of the BeanHeads library.

BeanHeads

A customizable cartoon avatar generator for Dart and Flutter. Generates SVG strings that can be used anywhere.

Dart port of BeanHeads by Robert Broersma.

Features

• 17 customizable dimensions (eyes, hair, clothing, accessories, etc.)
• Random avatar generation with optional seed for deterministic results
• SVG string generation -- the core produces plain SVG strings you can use anywhere
• Flutter widget included for easy integration (requires Flutter SDK)
• Immutable configuration with copyWith support
• Value equality on BeanheadConfig and ColorPair
• SVG caching in the Beanhead widget for efficient rebuilds
• Theming support via BeanheadsTheme

Installation

Add beanheads to your project:

flutter pub add beanheads

Or manually add it to your pubspec.yaml:

dependencies:
  beanheads: any

Then run flutter pub get.

Usage

Generate SVG String (Pure Dart)

import 'package:beanheads/beanheads.dart';

// With specific configuration
final config = BeanheadConfig(
  skinTone: SkinTone.light,
  eyes: Eyes.happy,
  hair: Hair.long,
  hairColor: HairColor.brown,
  clothing: Clothing.dressShirt,
);

final svgString = generateAvatar(config);

// Random avatar
final randomConfig = BeanheadConfig.random();
final randomSvg = generateAvatar(randomConfig);

// Deterministic random avatar (same seed = same avatar)
final seededConfig = BeanheadConfig.random(random: Random(42));

Flutter Widget

import 'package:beanheads/beanheads.dart';

// With configuration
Beanhead(
  config: BeanheadConfig(
    eyes: Eyes.heart,
    mouth: Mouth.grin,
    hair: Hair.afro,
    accessory: Accessory.shades,
  ),
  width: 200,
  height: 200,
)

// Random avatar
Beanhead.random(
  width: 200,
  height: 200,
)

Immutable Updates with copyWith

final base = BeanheadConfig(eyes: Eyes.normal);
final updated = base.copyWith(eyes: Eyes.happy, hair: Hair.afro);

Customization Options

Option	Values
skinTone	light, yellow, brown, dark, red, black
eyes	normal, leftTwitch, happy, content, squint, simple, dizzy, wink, heart
eyebrows	raised, leftLowered, serious, angry, concerned
mouth	grin, sad, openSmile, lips, open, serious, tongue
hair	none, long, bun, short, pixie, balding, buzz, afro, bob
facialHair	none, stubble, mediumBeard
clothing	naked, shirt, dressShirt, vneck, tankTop, dress
accessory	none, roundGlasses, tinyGlasses, shades
graphic	none, redwood, gatsby, vue, react, graphQL
hat	none, beanie, turban
body	chest, breasts
hairColor	blonde, orange, black, white, brown, blue, pink
clothingColor	white, blue, black, green, red
hatColor	white, blue, black, green, red
lipColor	red, purple, pink, turquoise, green
faceMaskColor	white, blue, black, green, red
lashes	true, false
mask	true, false (circular background mask)
faceMask	true, false (COVID-style face mask)

Example App

An interactive demo app is included that lets you customize avatars in real-time with dropdown selectors, SVG preview thumbnails, and live preview.

Running the Example

cd example
flutter pub get

macOS

flutter run -d macos

Windows

flutter run -d windows

Linux

flutter run -d linux

iOS

flutter run -d ios

Android

flutter run -d android

Web

flutter run -d chrome

API Reference

BeanheadConfig

Configuration class holding all avatar customization options. Supports:

• const constructor with sensible defaults
• BeanheadConfig.random({Random? random}) -- generate a random configuration, optionally seeded for deterministic results
• copyWith(...) -- create a modified copy (immutable updates)
• Value equality (==, hashCode) and toString

generateAvatar(BeanheadConfig config, {BeanheadsTheme? theme})

Generates a complete avatar as an SVG string. Accepts an optional theme for color customization.

Beanhead Widget

A StatefulWidget that renders an avatar from a BeanheadConfig. The SVG is cached internally and only regenerated when config or theme changes.

Beanhead(config: myConfig, width: 200, height: 200)

Beanhead.random()

Factory constructor that creates a widget with a random configuration.

Beanhead.random(width: 200, height: 200)
Beanhead.random(random: Random(42))  // deterministic

BeanheadsTheme / ColorPair

BeanheadsTheme holds all color mappings (skin, hair, clothing, etc.) used during SVG generation. ColorPair represents a base color and its shadow variant. A defaultTheme is provided out of the box.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

Credits

Based on BeanHeads by Robert Broersma, licensed under MIT.

License

MIT