Migration Guide

v3.0.0 is the current release and the only one you should install. This page covers both upgrade paths: from v2 (the style-based API, unchanged in shape) and from v1 (the original DOM-element API).

Do not install v1 or v2

Neither line is supported. v2.0.0 is on npm, but its tarballs cannot be loaded by Node at all — they ship ESM without "type": "module" and with extensionless relative imports, so only a bundler doing node10-style resolution can resolve them. Versions 2.1.0 through 2.6.0 were never published. See Versions & Support for the full picture.

Which path applies to you

You are on	Effort
v2.x (createAvatar(style, options))	Small — two import changes at most
v1.x (createAvatar({ name }))	Larger — the whole API changed
Nothing yet	Skip this page, go to Installation

Upgrading from v2

Avatar output is byte-identical between 2.x and 3.0.0 — no avatar your users already have will change. Only two things moved, and both are compile-time.

1. Style option types moved into their style packages

In v2, @avatar-generator/core declared every style’s option type — FacesOptions, AnimeOptions, GradientOptions and 26 more. Core therefore had to know about all eleven styles, and a style published by anyone else could not be typed at all. Each style now owns and exports its own option type.

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

The types themselves are unchanged, and the style packages already re-exported them in v2 — so if you were already importing from the style package, there is nothing to do. Core now declares only AvatarOptions, Style, Random, AvatarResult and the deprecated LegacyAvatarOptions.

This is what lets you publish a style of your own; see Creating Custom Styles.

2. The Angular component is standalone

@avatar-generator/angular is now built with ng-packagr as a real Angular Package Format library (FESM2022, partial Ivy), so AOT builds can consume it. Previously it shipped plain tsc output, which made a consumer’s AOT build fall back to the JIT compiler and fail with “needs to be compiled using the JIT compiler, but ‘@angular/compiler’ is not available”.

AvatarComponent is also standalone: true, because components have been standalone by default since Angular 19 and declaring one in an NgModule is an error:

@Component({
  imports: [AvatarComponent],
  template: `<avatar-generator [style]="style" [options]="options" />`,
})

AvatarModule still works and now re-exports the standalone component, so existing imports: [AvatarModule] code needs no change. Supported Angular versions widen to ^17 || ^18 || ^19 || ^20 || ^21.

Note

Angular Package Format is ESM-only — Angular dropped CommonJS and UMD output in v13 — so @avatar-generator/angular has no require() entry point. Every other package ships both ESM and CommonJS.

Everything else in 3.0.0 is a fix

These need no action from you, but they are why upgrading is worth it:

• Published packages are loadable from Node at all, as both ESM and CommonJS
• @avatar-generator/web-component no longer throws ReferenceError: HTMLElement is not defined when imported during a Next.js, Nuxt, Astro or SvelteKit server render
• register(tagName) in the web component works; it previously always threw NotSupportedError
• @avatar-generator/svelte ships a preprocessed component, so it compiles without a preprocessor configured
• Tarballs contain only dist/ and the licence, not src/ and tsconfigs

Upgrading from v1

v1 generated an HTML <div> with CSS-styled initials. v2 replaced it with deterministic SVG and pluggable styles, and v3 keeps that API unchanged. If you are still on v1, you are moving to the current API in one step.

v1	v3
HTML element output	SVG string output
Single initials style	11 pluggable style packages
name prop	seed prop
Styles bundled in core	Separate, tree-shakeable packages

Installation

A style package is no longer optional — core renders nothing on its own.

npm install @avatar-generator/core @avatar-generator/style-initials

Core package

v1:

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

const element = createAvatar({
    name: "Hugo GB",
    backgroundColor: "#4CAF50",
    textColor: "#fff",
    fontSize: "48px",
    shape: "circle",
});

document.body.appendChild(element);

v3:

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

const avatar = createAvatar(initials, {
    seed: "Hugo GB",
    size: 100,
    textColor: "#fff",
});

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

// …or insert the SVG markup directly
const div = document.createElement("div");
div.insertAdjacentHTML("beforeend", avatar.svg);
document.body.appendChild(div);

React

v1:

import { Avatar } from "@avatar-generator/react";

<Avatar name="Hugo GB" backgroundColor="#4CAF50" textColor="#fff" shape="circle" />;

v3:

import { Avatar } from "@avatar-generator/react";
import { initials } from "@avatar-generator/style-initials";

<Avatar style={initials} options={{ seed: "Hugo GB", size: 64, textColor: "#fff" }} alt="Hugo GB" />;

Angular

v1:

<avatar-generator [name]="'Hugo GB'" [backgroundColor]="'#4CAF50'" [textColor]="'#fff'" [shape]="'circle'" />

v3 — note the imports: [AvatarComponent], which v1 and v2 did not need:

import { Component } from "@angular/core";
import { AvatarComponent } from "@avatar-generator/angular";
import { initials } from "@avatar-generator/style-initials";

@Component({
    selector: "app-user-avatar",
    imports: [AvatarComponent],
    template: `<avatar-generator [style]="initialsStyle" [options]="options" alt="Hugo GB" />`,
})
export class UserAvatarComponent {
    initialsStyle = initials;
    options = { seed: "Hugo GB", size: 64 };
}

Option mapping

v1 option	v3 equivalent	Notes
name	seed	Drives generation
name	options.name	For the displayed initials (initials style)
backgroundColor	colors	Now an array — a palette to pick from
textColor	options.textColor	Initials style only
fontSize	—	Derived from size
shape: "circle"	square: false	The default
shape: "square"	square: true
width/height	size	Single dimension; avatars are square
tooltip	—	Set title on your own wrapper element

The v1 API is still present, but deprecated

createAvatarElement is the original v1 function, kept so you can migrate incrementally rather than in one commit:

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

// Still works. Deprecated — DOM-only, not deterministic SVG, and will be
// removed in a future major.
const element = createAvatarElement({ name: "Hugo GB", backgroundColor: "#4CAF50" });

Caution

createAvatarElement calls document.createElement, so it throws during server-side rendering. createAvatar returns a plain string and runs anywhere. Treat the legacy function as a temporary bridge, not a supported path.

After upgrading

• Skim the API Reference — every base and style option
• Compare the eleven styles in the Style Gallery
• Check the Cookbook for groups, fallbacks, theming, SSR