navii_dart

Pure-Dart deterministic mascot avatar generator. Feed it a string — any string — and get back a complete, self-contained SVG. Same string → identical SVG on every platform, every time, with no network, no database, no state.

A Dart port of navii by uxderrick.
For the Flutter widget, see navii_flutter.

Features

🎭 22M+ unique avatars — 22 palettes × 8 bodies × 10 eyes × 10 mouths × 5 antennae × 7 accessories × 3 backgrounds × 13 toppers
🔒 Deterministic — same seed always produces byte-identical SVG output
📴 Fully offline — no network calls, no external assets
🪶 Zero dependencies — pure Dart, no runtime packages
🌐 All platforms — native, web, server, Flutter

Installation

dependencies:
  navii_dart: ^0.1.0

Quick start

import 'package:navii_dart/navii_dart.dart';

// Returns a complete, self-contained SVG string
final String svg = createAvatar('user-123');

// Same seed → identical output, every time
assert(createAvatar('alice') == createAvatar('alice'));

// Use it anywhere SVG strings are accepted
final String svgString = createAvatar('bob@example.com');

Usage

Basic avatar

final svg = createAvatar('alice');
// → '<svg xmlns="http://www.w3.org/2000/svg" ...>...</svg>'

Force a specific palette

final svg = createAvatar('alice', AvatarOptions(paletteId: 'violet'));

Available palette IDs: indigo mint amber sky violet cyan rose lime peach teal sand plum coral forest slate fuchsia terracotta navy lavender charcoal butter aqua

Override the background shape

final svg = createAvatar('alice', AvatarOptions(background: BackgroundId.ring));
final svg = createAvatar('alice', AvatarOptions(background: BackgroundId.square));
final svg = createAvatar('alice', AvatarOptions(background: BackgroundId.circle));

Custom size

final svg = createAvatar('alice', AvatarOptions(size: 128));

Lower-level API

// Resolve the spec without rendering
final AvatarSpec spec = selectAvatar('alice');
print(spec.body);         // e.g. BodyShapeId.tall
print(spec.palette.id);   // e.g. 'violet'

// Render a pre-resolved spec
final String svg = renderAvatar(spec);

Seed guidance

Use as seed	Notes
Database user ID	✅ Best — stable, unique
UUID	✅ Great
Email address	✅ Fine — changes if email changes
Display name	⚠️ OK — changes if user renames

If the seed changes, the avatar changes. Choose something stable.

How it works

The seed string is hashed with cyrb53 → two 32-bit integers
Those seed the sfc32 PRNG
The PRNG picks one variant from each of 8 part categories, in order
The parts are composed into a single inline SVG string

The algorithm is a faithful port of the original JavaScript navii engine. Output is byte-identical across Dart native, web, and the original JS implementation.