Skip to content
@avatar-generator Docs

Installation

Requirements

  • Node.js 18+ for server-side or build-time use
  • Any bundler, or none — packages ship both ESM and CommonJS with a conditional exports map and per-condition type declarations
  • @avatar-generator/angular is the one exception: Angular Package Format is ESM-only, so that package has no require() entry point

Quick start

You always need two things: @avatar-generator/core, which holds createAvatar, and at least one style package, which does the drawing. Core renders nothing on its own.

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

That is enough for plain JavaScript or TypeScript — see Manual Usage. Add a framework wrapper below if you want a component instead of a string.

Framework packages

Each wrapper declares its framework as a peer dependency, so it uses the version your app already pins.

React

React 18 or 19.

Terminal window
npm install @avatar-generator/core @avatar-generator/react @avatar-generator/style-initials

Vue

Vue 3.

Terminal window
npm install @avatar-generator/core @avatar-generator/vue @avatar-generator/style-initials

Svelte

Svelte 4 or 5. The published component is already preprocessed to plain JavaScript, so no preprocessor configuration is needed.

Terminal window
npm install @avatar-generator/core @avatar-generator/svelte @avatar-generator/style-initials

Angular

Angular 17 through 21. Shipped as an Angular Package Format library (FESM2022, partial Ivy), so AOT builds consume it directly.

Terminal window
npm install @avatar-generator/core @avatar-generator/angular @avatar-generator/style-initials

Web component

No framework peer dependency — it is a standard custom element, usable from any framework or from a plain HTML page.

Terminal window
npm install @avatar-generator/core @avatar-generator/web-component @avatar-generator/style-initials

Available styles

Every style is its own tree-shakeable package. Install only the ones you import.

PackageDescription
@avatar-generator/style-initialsLetter initials on colored backgrounds
@avatar-generator/style-geometricGitHub-style symmetrical identicon grids
@avatar-generator/style-pixels8-bit retro pixel faces
@avatar-generator/style-ringsConcentric rings, segmented and dashed variants
@avatar-generator/style-facesMinimal flat geometric faces
@avatar-generator/style-illustratedDetailed cartoon faces with accessories
@avatar-generator/style-animeAnime/manga-inspired faces with expressive eyes
@avatar-generator/style-abstractMondrian/Kandinsky/Bauhaus-inspired compositions
@avatar-generator/style-emojiYellow emoji-style expressive faces
@avatar-generator/style-animalsCute animal avatars (cat, dog, fox, panda, …)
@avatar-generator/style-gradientSmooth gradients with pattern overlays

To install several at once:

Terminal window
npm install @avatar-generator/style-geometric @avatar-generator/style-pixels @avatar-generator/style-rings @avatar-generator/style-faces @avatar-generator/style-illustrated @avatar-generator/style-anime @avatar-generator/style-abstract @avatar-generator/style-emoji @avatar-generator/style-animals @avatar-generator/style-gradient

Keeping versions in step

All seventeen packages are released together at one version. Mixing majors is not supported, so upgrade them as a set.

Verify your install

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


const a = createAvatar(initials, { seed: "hello" });
const b = createAvatar(initials, { seed: "hello" });


console.log(a.svg === b.svg); // true — same seed, same bytes

Next steps