API Reference

Everything on this page describes v3.x, the current and only supported release line. See Versions & Support.

createAvatar

The main function for generating avatars.

import { createAvatar } from "@avatar-generator/core";
import { initials } from "@avatar-generator/style-initials";

const avatar = createAvatar(initials, { seed: "Hugo GB" });

Parameters

Parameter	Type	Description
style	Style<T>	The avatar style to use
options	T extends AvatarOptions	Style-specific options

Returns

Property	Type	Description
svg	string	The generated SVG string
toDataUri()	() => string	Returns a data URI for use in img src

Common Options

All styles accept these base options:

Option	Type	Default	Description
seed	string	(required)	Seed for deterministic generation
size	number	64	Avatar size in pixels
colors	string[]	(style default)	Custom color palette
square	boolean	false	Use square shape instead of circle
transparent	boolean	false	Make background transparent
border	{ width: number, color: string }	-	Border configuration
rotate	number	0	Rotation in degrees
flip	boolean	false	Horizontal flip
scale	number	1	Scale factor

Style-Specific Options

Each style owns its option type and exports it from its own package — not from @avatar-generator/core, which declares only the style contract itself: AvatarOptions, Style, Random, AvatarResult, and the deprecated LegacyAvatarOptions.

import { faces, type FacesOptions } from "@avatar-generator/style-faces";

That is what lets you publish a style of your own without core needing to know it exists. See Creating Custom Styles.

Changed in v3

In v2 these types were declared by @avatar-generator/core. Update the import path when you upgrade — the types themselves are unchanged. See the Migration Guide.

Options you leave unset are chosen deterministically from the seed. Options listed with a fixed set of values are validated at runtime: passing anything else throws an Error naming the style, the option and the accepted values, rather than silently falling back to a random choice.

Each style also exports the arrays behind its literal unions — HAIR_STYLES, EYE_STYLES, MOUTH_STYLES, CENTER_STYLES, COMPOSITIONS, EXPRESSIONS, ANIMALS, DIRECTIONS, PATTERNS — so a picker UI can be generated from them instead of hand-maintained.

InitialsOptions

For @avatar-generator/style-initials:

Option	Type	Default	Description
name	string	seed	Name to extract initials from
fontFamily	string	"sans-serif"	Font family
fontWeight	number	600	Font weight
textColor	string	"#fff"	Text color

GeometricOptions

For @avatar-generator/style-geometric (Identicon):

Option	Type	Default	Description
gridSize	number	5	Grid size (odd recommended for symmetry)
padding	number	1	Padding cells around the pattern
foregroundColor	string	(from palette)	Override foreground color

PixelsOptions

For @avatar-generator/style-pixels (Pixel Faces):

Option	Type	Default	Description
pixelSize	number	8	Pixel grid size
skinTones	string[]	SKIN_TONES	Custom skin tone palette
accessories	boolean	true	Enable accessories like glasses (15% chance)
featureColor	string	"#2C1810"	Override eye/mouth color

RingsOptions

For @avatar-generator/style-rings:

Option	Type	Default	Description
ringCount	number	4	Number of rings
ringGap	number	2	Gap between rings
segmented	boolean	true	Allow segmented pie-slice rings
dashed	boolean	true	Allow dashed rings
centerStyle	string	"solid"	Center decoration: "solid", "dot", "ring", "diamond", "none"

FacesOptions

For @avatar-generator/style-faces:

Option	Type	Default	Description
skinTones	string[]	SKIN_TONES	Custom skin tone palette
featureColor	string	"#2C1810"	Override feature color
eyebrows	boolean	true	Enable eyebrows (50% chance)
ears	boolean	true	Enable ears (40% chance)
nose	boolean	true	Enable nose (30% chance)
mouthStyle	string	(random)	Override mouth: "line", "rect-smile", "open-rect", "zigzag", "dot"
eyeStyle	string	(random)	Override eyes: "dots", "rectangles", "lines", "round"
hairStyle	string	(random)	Override hair: "none", "flat-top", "cap", "side-swept", "spiky", "round-top", "mohawk", "beanie"

IllustratedOptions

For @avatar-generator/style-illustrated:

Option	Type	Default	Description
skinTones	string[]	SKIN_TONES	Custom skin tone palette
eyeColors	string[]	EYE_COLORS	Custom eye color palette
hairStyle	string	(random)	Override hair (12 styles): "bald", "buzz", "short", "medium", "long", "curly", "wavy", "mohawk", "afro", "ponytail", "bangs", "sidepart"
eyeStyle	string	(random)	Override eyes (8 styles): "round", "almond", "narrow", "wide", "sleepy", "winking", "looking", "glasses"
eyebrowStyle	string	(random)	Override eyebrows (6 styles): "natural", "thick", "thin", "raised", "furrowed", "unibrow"
noseStyle	string	(random)	Override nose (5 styles): "small", "pointed", "round", "long", "button"
mouthStyle	string	(random)	Override mouth (8 styles): "smile", "bigSmile", "neutral", "frown", "open", "smirk", "tongue", "teeth"
glasses	boolean	true	Enable glasses (20% chance, 3 types)
hat	boolean	true	Enable hat (10% chance, 3 types)
earrings	boolean	true	Enable earrings (8% chance)
facialHair	boolean	true	Enable facial hair (15% chance, 3 types)

AnimeOptions

For @avatar-generator/style-anime:

Option	Type	Default	Description
skinTones	string[]	SKIN_TONES	Custom skin tone palette
eyeColors	string[]	EYE_COLORS	Custom eye color palette
hairStyle	string	(random)	Override hair (10 styles): "short-spiky", "medium-messy", "long-straight", "twin-tails", "ponytail", "side-swept", "wild", "bob", "hime-cut", "shaggy"
eyeStyle	string	(random)	Override eyes (8 styles): "normal", "sparkly", "determined", "gentle", "cat", "half-closed", "closed-happy", "surprised"
mouthStyle	string	(random)	Override mouth (6 styles): "small-smile", "open-small", "cat-mouth", "line", "pout", "grin"
noseStyle	string	(random)	Override nose (3 styles): "dot", "line", "shadow"
expression	string	—	Reserved for future expression overrides; currently has no effect
bangs	boolean	(random, 60%)	Enable bangs over forehead
ahoge	boolean	(random, 40%)	Enable ahoge hair strand on top
blush	boolean	(random, 35%)	Enable blush on cheeks
accessories	boolean	true	Enable accessories (bandaid 5%, headband 8%)

AbstractOptions

For @avatar-generator/style-abstract:

Option	Type	Default	Description
composition	string	(random)	Override composition: "mondrian", "kandinsky", "bauhaus"
shapeCount	number	3	Number of accent shapes in the Kandinsky composition

EmojiOptions

For @avatar-generator/style-emoji:

Option	Type	Default	Description
expression	string	(random)	Override expression: "happy", "laughing", "cool", "wink", "love", "sad", "angry", "surprised", "sleepy", "neutral"
faceColor	string	(random)	Override the face fill color

AnimalsOptions

For @avatar-generator/style-animals:

Option	Type	Default	Description
animal	string	(random)	Override animal: "cat", "dog", "bear", "fox", "panda", "bunny", "frog", "monkey"
furTones	string[]	(earth tones)	Custom fur palette

GradientOptions

For @avatar-generator/style-gradient:

Option	Type	Default	Description
direction	string	(random)	Override direction: "linear", "radial", "diagonal"
pattern	string	(random)	Overlay pattern: "none", "dots", "stripes", "waves", "grid"
colorStops	number	2	Number of color stops in the gradient (2 or 3)

Utilities

createRandom

Creates a deterministic random number generator from a seed string.

import { createRandom } from "@avatar-generator/core";

const random = createRandom("my-seed");

random.next(); // Float between 0 and 1
random.int(0, 10); // Integer between 0 and 9
random.pick(["a", "b"]); // Random item from array
random.bool(0.7); // Boolean with 70% true probability
random.shuffle([1, 2, 3]); // Shuffle array in place

DEFAULT_COLORS

The default color palette used by styles:

import { DEFAULT_COLORS } from "@avatar-generator/core";

// ["#FF6B6B", "#4ECDC4", "#45B7D1", "#96CEB4", "#FFEAA7",
// "#DDA0DD", "#98D8C8", "#F7DC6F", "#BB8FCE", "#85C1E9"]

SKIN_TONES

Skin tone palette for face-based styles (Pixel Faces, Faces, Illustrated, Anime):

import { SKIN_TONES } from "@avatar-generator/core";

// ["#FFDBB4", "#EAC086", "#C68B59", "#A0674B", "#8D5524", "#613915"]

EYE_COLORS

Eye color palette for the Illustrated and Anime styles:

import { EYE_COLORS } from "@avatar-generator/core";

// ["#634E34", "#2E536F", "#3D6B45", "#89724B", "#3B3024"]

validateOption

Throws if a categorical option is not one of the accepted values. Does nothing when the value is undefined, since absence means “pick from the seed”. Style packages call it on every literal-union option; custom styles should too.

import { validateOption } from "@avatar-generator/core";

validateOption("checker", "pattern", options.pattern, PATTERNS);
// Error: [@avatar-generator/style-checker] Invalid pattern: "wobbly".
// Expected one of: "classic", "diagonal", "dotted".

SVG utilities

Low-level building blocks. buildSvg is the only one most styles need; the rest are exported for styles that assemble their own wrapper.

import {
    buildSvg,
    buildTransform,
    createBackground,
    createBorder,
    createCircleClip,
    createSquareClip,
    createSvgOpen,
    escapeXml,
    wrapWithTransform,
} from "@avatar-generator/core";

// buildSvg(content, options, backgroundColor) Complete SVG: viewBox, clip, background, border, transform
// buildTransform(options) The transform attribute for rotate/flip/scale
// createBackground(size, color, transparent) Background rect
// createBorder(size, width, color, square) Border element
// createCircleClip(id, size) Circular clip path
// createSquareClip(id, size) Square clip path
// createSvgOpen(size) Opening <svg> tag
// escapeXml(text) Escapes text for SVG <text> nodes
// wrapWithTransform(content, options) Wraps content in a transform group

Note

Together with createAvatar and the deprecated createAvatarElement, the utilities above are everything @avatar-generator/core exports at runtime. Anything not listed — the seed hash behind clip-path ids, for instance — is internal and may change in a minor release.

Types

@avatar-generator/core declares five types and no more: AvatarOptions (the common options above), Style, AvatarResult, Random, and the deprecated LegacyAvatarOptions. Everything style-specific lives in the style’s own package.

Style Interface

interface Style<T extends AvatarOptions = AvatarOptions> {
    name: string;
    create(options: T): AvatarResult;
}

AvatarResult

interface AvatarResult {
    svg: string;
    toDataUri(): string;
}

Random

interface Random {
    next(): number;
    int(min: number, max: number): number;
    pick<T>(array: T[]): T;
    bool(probability?: number): boolean;
    shuffle<T>(array: T[]): T[];
}

LegacyAvatarOptions

The v1 options shape, kept only for createAvatarElement below.

interface LegacyAvatarOptions {
    name: string;
    backgroundColor?: string | string[];
    gradientDirection?: "vertical" | "horizontal";
    textColor?: string;
    fontSize?: string;
    shape?: "circle" | "square";
    width?: string;
    height?: string;
    tooltip?: boolean;
    additionalClasses?: string;
}

Deprecated: the v1 element API

createAvatarElement is the original v1 function. It builds a DOM <div> with CSS-styled initials — not deterministic SVG, and not a style. It survives so a v1 codebase can migrate incrementally.

import { createAvatarElement } from "@avatar-generator/core";

const element = createAvatarElement({ name: "Hugo GB", backgroundColor: "#4CAF50" });
document.body.appendChild(element);

Caution

Deprecated, and not a supported path for new code. It calls document.createElement, so it throws during server-side rendering; it ignores every style and every option on this page; and it will be removed in a future major. Use createAvatar with a style instead — see the Migration Guide.