Migration Guide (v1 to v2)

Version 2.0 introduces a new style-based architecture with SVG output. This guide covers the breaking changes and how to update your code.

Key Changes

v1	v2
HTML element output	SVG string output
Single initials style	7 pluggable styles
name prop	seed prop
Styles bundled in core	Separate style packages

Installation Changes

v1:

npm install @avatar-generator/react

v2:

npm install @avatar-generator/react @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);

v2:

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 image src
const img = document.createElement("img");
img.src = avatar.toDataUri();
document.body.appendChild(img);

// Or insert SVG 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"
/>

v2:

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'"
/>

v2:

// In component:
import { initials } from "@avatar-generator/style-initials";
initialsStyle = initials;

// In template:
<avatar-generator
[style]="initialsStyle"
[options]="{ seed: 'Hugo GB', size: 64 }"
alt="Hugo GB"
/>

Option Mapping

v1 Option	v2 Option	Notes
name	seed	Used for generation
name	options.name	For initials display (initials style only)
backgroundColor	colors	Now an array for palette
textColor	options.textColor	Initials style only
fontSize	-	Calculated from size
shape: "circle"	square: false	Default is circle
shape: "square"	square: true
width/height	size	Single dimension (square)

Legacy Support

The v1 API is still available as createAvatarElement for gradual migration:

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

// Still works, but deprecated
const element = createAvatarElement({
name: "Hugo GB",
backgroundColor: "#4CAF50",
});

We recommend migrating to the new API for access to all styles and features.