Skip to content

Avatar Generator 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

ParameterTypeDescription
styleStyle<T>The avatar style to use
optionsT extends AvatarOptionsStyle-specific options

Returns

PropertyTypeDescription
svgstringThe generated SVG string
toDataUri()() => stringReturns a data URI for use in img src

Common Options

All styles accept these base options:

OptionTypeDefaultDescription
seedstring(required)Seed for deterministic generation
sizenumber64Avatar size in pixels
colorsstring[](style default)Custom color palette
squarebooleanfalseUse square shape instead of circle
transparentbooleanfalseMake background transparent
border{ width: number, color: string }-Border configuration
rotatenumber0Rotation in degrees
flipbooleanfalseHorizontal flip
scalenumber1Scale factor
theme"light" | "dark" | "high-contrast" | "auto" | AvatarTheme-Colour theme
animationboolean | "blink" | "breathe" | arrayfalseIdle animation
classesboolean | stringfalseCSS hooks
titlestring-Accessible name for inlined SVG
descriptionstring-Accessible description

These are all opt-in, and leave the output unchanged when unset.

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.

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:

OptionTypeDefaultDescription
namestringseedName to extract initials from
fontFamilystring"sans-serif"Font family
fontWeightnumber600Font weight
textColorstring"#fff"Text color

GeometricOptions

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

OptionTypeDefaultDescription
gridSizenumber5Grid size (odd recommended for symmetry)
paddingnumber1.5Padding cells around the pattern, which keeps its corners inside a circle
foregroundColorstring(from palette)Override foreground color

PixelsOptions

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

OptionTypeDefaultDescription
pixelSizenumber12Pixels per side of the canvas, at least 12
skinTonesstring[]SKIN_TONESCustom skin tone palette
accessoriesbooleantrueEnable accessories like glasses (15% chance)
featureColorstring"#2C1810"Override eye/mouth color

RingsOptions

For @avatar-generator/style-rings:

OptionTypeDefaultDescription
ringCountnumber3Number of rings
ringGapnumber2Gap between rings
segmentedbooleantrueAllow segmented pie-slice rings
dashedbooleantrueAllow dashed rings
centerStylestring"solid"Center decoration: "solid", "dot", "ring", "diamond", "none"

FacesOptions

For @avatar-generator/style-faces:

OptionTypeDefaultDescription
skinTonesstring[]SKIN_TONESCustom skin tone palette
featureColorstring"#2C1810"Override feature color
eyebrowsbooleantrueEnable eyebrows (50% chance)
earsbooleantrueEnable ears (40% chance)
nosebooleantrueEnable nose (30% chance)
mouthStylestring(random)Override mouth: "line", "rect-smile", "open-rect", "zigzag", "dot"
eyeStylestring(random)Override eyes: "dots", "rectangles", "lines", "round"
hairStylestring(random)Override hair: "none", "flat-top", "cap", "side-swept", "spiky", "round-top", "mohawk", "beanie"

IllustratedOptions

For @avatar-generator/style-illustrated:

OptionTypeDefaultDescription
skinTonesstring[]SKIN_TONESCustom skin tone palette
eyeColorsstring[]EYE_COLORSCustom eye color palette
hairStylestring(random)Override hair (12 styles): "bald", "buzz", "short", "medium", "long", "curly", "wavy", "mohawk", "afro", "ponytail", "bangs", "sidepart"
eyeStylestring(random)Override eyes (8 styles): "round", "almond", "narrow", "wide", "sleepy", "winking", "looking", "glasses"
eyebrowStylestring(random)Override eyebrows (6 styles): "natural", "thick", "thin", "raised", "furrowed", "unibrow"
noseStylestring(random)Override nose (5 styles): "small", "pointed", "round", "long", "button"
mouthStylestring(random)Override mouth (8 styles): "smile", "bigSmile", "neutral", "frown", "open", "smirk", "tongue", "teeth"
glassesbooleantrueEnable glasses (20% chance, 3 types)
hatbooleantrueEnable hat (10% chance, 3 types)
earringsbooleantrueEnable earrings (8% chance)
facialHairbooleantrueEnable facial hair (15% chance, 3 types)

AnimeOptions

For @avatar-generator/style-anime:

OptionTypeDefaultDescription
skinTonesstring[]SKIN_TONESCustom skin tone palette
eyeColorsstring[]EYE_COLORSCustom eye color palette
hairStylestring(random)Override hair (10 styles): "short-spiky", "medium-messy", "long-straight", "twin-tails", "ponytail", "side-swept", "wild", "bob", "hime-cut", "shaggy"
eyeStylestring(random)Override eyes (8 styles): "normal", "sparkly", "determined", "gentle", "cat", "half-closed", "closed-happy", "surprised"
mouthStylestring(random)Override mouth (6 styles): "small-smile", "open-small", "cat-mouth", "line", "pout", "grin"
noseStylestring(random)Override nose (3 styles): "dot", "line", "shadow"
expressionstring—Reserved for future expression overrides; currently has no effect
bangsboolean(random, 60%)Enable bangs over forehead
ahogeboolean(random, 40%)Enable ahoge hair strand on top
blushboolean(random, 35%)Enable blush on cheeks
accessoriesbooleantrueEnable accessories (bandaid 5%, headband 8%)

AbstractOptions

For @avatar-generator/style-abstract:

OptionTypeDefaultDescription
compositionstring(random)Override composition: "mondrian", "kandinsky", "bauhaus"
shapeCountnumber3Number of accent shapes in the Kandinsky composition

EmojiOptions

For @avatar-generator/style-emoji:

OptionTypeDefaultDescription
expressionstring(random)Override expression: "happy", "laughing", "cool", "wink", "love", "sad", "angry", "surprised", "sleepy", "neutral"
faceColorstring(random)Override the face fill color

AnimalsOptions

For @avatar-generator/style-animals:

OptionTypeDefaultDescription
animalstring(random)Override animal: "cat", "dog", "bear", "fox", "panda", "bunny", "frog", "monkey"
furTonesstring[](earth tones)Custom fur palette

GradientOptions

For @avatar-generator/style-gradient:

OptionTypeDefaultDescription
directionstring(random)Override direction: "linear", "radial", "diagonal"
patternstring(random)Overlay pattern: "none", "dots", "stripes", "waves", "grid"
colorStopsnumber2Number of color stops in the gradient (2 or 3)

Platform API

FunctionGuide
defineStyle(definition)Custom styles
mixStyles(base, features, options?)Mixing styles
createAvatarTransition(style, from, to, options?)Animation
adaptForImage(options), adaptGroupForImage(...)Animation
viewerPreferences(), subscribeViewerPreferences()Animation
defineTheme(theme), resolveTheme(theme)Themes
createAvatarGroup(style, items, options?)Avatar groups
renderToString(style, options, render?)Server-side rendering

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

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);

Built by · MIT licensed