avatar_builder 0.3.0

Flutter widget that renders avataaars-style cartoon avatars from customizable attributes using SVG.

Avatar Builder

A Flutter widget that renders customizable avataaars-style cartoon avatars. Choose from 34 hairstyles, 12 eye styles, 13 eyebrow styles, 12 mouth styles, 9 clothing options, and more — or generate a random avatar with a single line of code.

Live Demo · API Reference

Features

• 140+ SVG fragments composable into millions of unique avatars
• Fully customizable: hair, eyes, eyebrows, mouth, facial hair, clothing, accessories, skin color
• Random avatar generation via Avataaar.random()
• Lightweight: optimized SVG assets (~194 KB total)
• Built-in LRU cache for fast rendering
• Circle or transparent background styles
• Pixel-perfect fidelity to the original avataaars React library

Getting started

Add avatar_builder to your pubspec.yaml:

dependencies:
  avatar_builder: ^0.3.0

Then run:

flutter pub get

Usage

Import the package:

import 'package:avatar_builder/avatar_builder.dart';

Display a random avatar

AvatarWidget(avatar: Avataaar.random())

Display a specific avatar

AvatarWidget(
  avatar: Avataaar(
    topType: TopType.shortHairShortFlat,
    accessoriesType: AccessoriesType.prescription01,
    hairColor: HairColor.brown.color,
    facialHairType: FacialHairType.blank,
    clotheType: ClotheType.hoodie,
    clotheColor: ClotheColor.blue01.color,
    eyeType: EyeType.defaultEye,
    eyebrowType: EyebrowType.defaultBrow,
    mouthType: MouthType.smile,
    skinColor: SkinColor.light.color,
  ),
)

Customize the size

AvatarWidget(
  avatar: Avataaar.random(),
  size: 200,
)

Use a shared cache

AvatarWidget uses SvgCache.instance by default to cache loaded SVG fragments in memory. You can also provide your own cache:

final cache = SvgCache(maxEntries: 256);

AvatarWidget(
  avatar: Avataaar.random(),
  cache: cache,
)

Extract the SVG string

Use toSvg() to get the composed SVG markup directly — useful for exporting, saving to a file, or server-side use:

final avatar = Avataaar(
  topType: TopType.shortHairShortFlat,
  eyeType: EyeType.happy,
  mouthType: MouthType.smile,
  skinColor: SkinColor.light.color,
);

final svgString = await avatar.toSvg(loadAsset: SvgCache.instance.load);
// svgString contains a complete <svg>...</svg> document
// with all colors applied.

For pure-Dart (non-Flutter) use, see avatar_builder_core which includes a FileAssetLoader for dart:io environments.

Customization options

Category	Enum	Options
Style	AvatarStyle	circle, transparent
Hair / Hat	TopType	34 styles (long hair, short hair, hats, turbans, hijab, etc.)
Hair color	HairColor	12 colors
Accessories	AccessoriesType	7 types (glasses, sunglasses, etc.)
Facial hair	FacialHairType	6 types
Eyes	EyeType	12 styles
Eyebrows	EyebrowType	13 styles
Mouth	MouthType	12 styles
Clothing	ClotheType	9 types
Clothing color	ClotheColor	15 colors
Graphic (on shirts)	GraphicType	11 designs
Skin	SkinColor	7 tones

Example app

A full interactive example is available in the example/ directory and deployed as a live demo.

To run it locally:

cd example
flutter run -d chrome

Contributing

Contributions are welcome! See DEVELOPMENT.md for how the SVG data is generated and how to work on the package.

Credits

Based on avataaars-generator by Fang-Pen Lin, using avatar artwork by Pablo Stanley.

License

BSD 2-Clause License — see LICENSE for details.