Skip to content
@avatar-generator Docs

Manual Usage

The core package provides a simple API to generate SVG avatars. Choose a style and pass options to create deterministic avatars.

Basic Usage

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


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


// Get the SVG string
console.log(avatar.svg);


// Or use as an image src
const img = document.createElement("img");
img.src = avatar.toDataUri();
document.body.appendChild(img);

Using Different Styles

Each style creates a unique visual representation:

import { createAvatar } from "@avatar-generator/core";
import { initials } from "@avatar-generator/style-initials";
import { geometric } from "@avatar-generator/style-geometric";
import { pixels } from "@avatar-generator/style-pixels";
import { rings } from "@avatar-generator/style-rings";
import { faces } from "@avatar-generator/style-faces";
import { illustrated } from "@avatar-generator/style-illustrated";
import { anime } from "@avatar-generator/style-anime";


// Same seed generates consistent avatars across styles
const seed = "user-123";


const initialsAvatar = createAvatar(initials, { seed });
const geometricAvatar = createAvatar(geometric, { seed });
const pixelsAvatar = createAvatar(pixels, { seed });
const ringsAvatar = createAvatar(rings, { seed });
const facesAvatar = createAvatar(faces, { seed });
const illustratedAvatar = createAvatar(illustrated, { seed });
const animeAvatar = createAvatar(anime, { seed });

Customization Options

All styles share common options:

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


const avatar = createAvatar(geometric, {
seed: "unique-id",
size: 128, // Avatar size in pixels
square: true, // Use square shape instead of circle
transparent: false, // Transparent background
colors: ["#FF6B6B", "#4ECDC4", "#45B7D1"], // Custom color palette
border: {
width: 2,
color: "#333",
},
rotate: 45, // Rotation in degrees
flip: false, // Horizontal flip
scale: 0.9, // Scale factor
});

Style-Specific Options

Initials Style

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


const avatar = createAvatar(initials, {
seed: "john.doe@example.com",
name: "Hugo GB", // Name to extract initials from (defaults to seed)
fontFamily: "Arial", // Font family
fontWeight: 700, // Font weight
textColor: "#ffffff", // Text color
});

Geometric Style (Identicon)

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


const avatar = createAvatar(geometric, {
seed: "unique-id",
gridSize: 5, // Grid size (default: 5, odd recommended)
padding: 1, // Padding cells around pattern (default: 1)
foregroundColor: "#2C3E50", // Override foreground color
});

Pixels Style (Pixel Faces)

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


const avatar = createAvatar(pixels, {
seed: "unique-id",
pixelSize: 8, // Pixel grid size (default: 8)
accessories: true, // Enable glasses (default: true, 15% chance)
featureColor: "#2C1810", // Override eye/mouth color
});

Rings Style

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


const avatar = createAvatar(rings, {
seed: "unique-id",
ringCount: 5, // Number of rings (default: 4)
ringGap: 3, // Gap between rings (default: 2)
segmented: true, // Allow segmented pie-slice rings (default: true)
dashed: true, // Allow dashed rings (default: true)
centerStyle: "diamond", // Center decoration: solid, dot, ring, diamond, none
});

Faces Style

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


const avatar = createAvatar(faces, {
seed: "unique-id",
featureColor: "#2C1810", // Override feature color
eyebrows: true, // Enable eyebrows (default: true, 50% chance)
ears: true, // Enable ears (default: true, 40% chance)
nose: true, // Enable nose (default: true, 30% chance)
hairStyle: "curly", // Override hair style
eyeStyle: "happy", // Override eye style
mouthStyle: "smile", // Override mouth style
});

Illustrated Style

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


const avatar = createAvatar(illustrated, {
seed: "unique-id",
hairStyle: "afro", // Override hair (12 styles)
eyeStyle: "round", // Override eyes (8 styles)
eyebrowStyle: "natural", // Override eyebrows (6 styles)
noseStyle: "button", // Override nose (5 styles)
mouthStyle: "bigSmile", // Override mouth (8 styles)
glasses: true, // Enable glasses (default: true, 20% chance)
hat: true, // Enable hat (default: true, 10% chance)
earrings: true, // Enable earrings (default: true, 8% chance)
facialHair: true, // Enable facial hair (default: true, 15% chance)
});

Anime Style

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


const avatar = createAvatar(anime, {
seed: "unique-id",
hairStyle: "twin-tails", // Override hair (10 styles)
eyeStyle: "sparkly", // Override eyes (8 styles)
mouthStyle: "cat-mouth", // Override mouth (6 styles)
noseStyle: "dot", // Override nose (3 styles)
bangs: true, // Enable bangs over forehead
ahoge: true, // Enable ahoge hair strand (default: 40% chance)
blush: true, // Enable blush on cheeks (default: 35% chance)
accessories: true, // Enable accessories (bandaid, headband)
});

Deterministic Generation

Avatars are deterministic - the same seed and options always produce the same result:

const avatar1 = createAvatar(initials, { seed: "user-123" });
const avatar2 = createAvatar(initials, { seed: "user-123" });


// avatar1.svg === avatar2.svg (always true)

This makes avatars perfect for user profiles, as each user gets a unique but consistent avatar based on their ID.