avatarka

Generate unique, customizable SVG avatars with multiple themes.

Features

• 14 Built-in Themes: People, animals, monsters, robots, aliens, ocean, dinosaurs, mythical, insects, birds, plants, food, weather, and gems
• Seed-based Generation: Generate deterministic avatars from any string (email, user ID, etc.)
• Fully Customizable: Every parameter can be tweaked via a typed API
• Minimal Dependencies: Single runtime dependency (pragmastat for PRNG)
• TypeScript First: Full type safety with exported types

Installation

npm install avatarka

Quick Start

Basic Usage

import { generateAvatar, generateParams } from 'avatarka';

// Generate random parameters and create an avatar
const params = generateParams('monsters');
const svg = generateAvatar('monsters', params);

// Insert into DOM
document.getElementById('avatar').innerHTML = svg;

Seed-based Generation

Generate consistent avatars from any string (great for user avatars):

import { randomAvatar, generateParams } from 'avatarka';

// One-liner: generate avatar from seed
const svg = randomAvatar('animals', '[email protected]');

// Same seed always produces the same avatar
const params1 = generateParams('monsters', 'user-123');
const params2 = generateParams('monsters', 'user-123');
// params1 and params2 are identical

API Reference

generateAvatar(theme, params)

Generate an SVG string from theme and parameters.

const svg = generateAvatar('robots', {
  backgroundShape: 'circle',
  bodyColor: '#95a5a6',
  accentColor: '#3498db',
  eyeColor: '#e74c3c',
  backgroundColor: '#2c3e50',
  headShape: 'square',
  antennaStyle: 'single',
  eyeStyle: 'round',
  mouthStyle: 'grille',
  hasPanel: 'no',
  panelLights: 3,
});

generateParams(theme, seed?)

Generate random parameters for a theme. Optionally pass a seed for deterministic output.

// Random
const params = generateParams('monsters');

// Deterministic
const params = generateParams('monsters', 'my-seed');

randomAvatar(theme, seed?)

Convenience function combining generateParams and generateAvatar.

const svg = randomAvatar('people', '[email protected]');

getDefaultParams(theme)

Get default parameters from the theme schema.

const defaults = getDefaultParams('monsters');

getThemeNames()

Get array of available theme names.

const themes = getThemeNames();
// ['people', 'animals', 'monsters', 'robots', 'aliens', 'ocean',
//  'dinosaurs', 'mythical', 'insects', 'birds', 'plants', 'food',
//  'weather', 'gems']

getTheme(theme)

Get theme metadata including name and parameter schema.

const { name, schema } = getTheme('animals');

Themes

| Theme | Description | |--------------|-----------------------------------------------------------------------------------------| | people | Human avatars with various hairstyles and accessories | | animals | Animal faces (cats, dogs, bears, bunnies, foxes, pandas, owls, koalas, penguins, lions) | | monsters | Cute monster characters with customizable features | | robots | Retro-futuristic robot heads with various features | | aliens | Extraterrestrial beings with various head shapes | | ocean | Ocean creatures (octopus, fish, jellyfish, crab, whale, seahorse, and more) | | dinosaurs | Prehistoric dinosaurs (trex, triceratops, stegosaurus, brachiosaurus, and more) | | mythical | Mythical creatures (dragon, unicorn, phoenix, griffin, yeti, and more) | | insects | Insects (butterfly, bee, ladybug, ant, beetle, dragonfly, and more) | | birds | Bird species (parrot, owl, penguin, flamingo, eagle, toucan, and more) | | plants | Plants (cactus, sunflower, rose, tulip, venus-flytrap, bonsai, and more) | | food | Food items (sushi, pizza, cupcake, ice-cream, donut, burger, and more) | | weather | Weather phenomena (sun, cloud, raindrop, snowflake, lightning, and more) | | gems | Gemstones (diamond, ruby, emerald, sapphire, amethyst, opal, and more) |

generateGallery(count, seed?, options?)

Generate a diverse gallery of avatars with guaranteed visual variety across all themes.

import { generateGallery } from 'avatarka';

const items = generateGallery(25, 'my-seed', {
  backgroundShape: 'circle',
});
// Returns: Array of { theme, params, svg }

PNG Generation (Browser-only)

Convert SVG avatars to PNG using the Canvas API:

import { generateAvatar, generateParams, svgToPng, svgToPngDataUrl } from 'avatarka';

const params = generateParams('monsters', '[email protected]');
const svg = generateAvatar('monsters', params);

// Get as PNG Blob
const blob = await svgToPng(svg, { size: 512 });

// Or as data URL
const dataUrl = await svgToPngDataUrl(svg, { size: 128 });

Note: These functions require a browser environment with Canvas support.

Related Packages

• avatarka-react - React components for avatarka

License

MIT