identicon-angular

An Angular (v21) library that generates deterministic, SVG avatars (identicons) from a GUID. The same GUID always produces the same face — a randomized head, glasses, eyes (with gaze), and mouth — over a contrast-checked color palette.

The generator is framework-agnostic at its core and exposed through a single standalone component.

Demo

Features

• Deterministic output — identical GUID yields an identical avatar
• Pure SVG, no canvas or runtime image assets
• Accessible contrast: palette is auto-tuned for legibility
• Fully configurable geometry and color constants
• Standalone component, ready for imports

Installation

npm install identicon-angular

Usage

Import the standalone component and bind a GUID:

import { Component } from '@angular/core';
import { IdenticonAngular } from 'identicon-angular';

@Component({
  selector: 'app-root',
  imports: [IdenticonAngular],
  template: `<app-identicon [guid]="userId" />`,
})
export class AppComponent {
  userId = 'd290f1ee-6c54-4b01-90e6-d701748f0851';
}

With configuration

Every generation constant can be overridden through the optional config input. Any omitted field falls back to its default.

<app-identicon
  [guid]="userId"
  [config]="{
    size: 96,
    syncedProbability: 0.5,
    palette: { minBackgroundContrast: 2.0, hueRange: { min: 0, max: 360 } }
  }"
/>

Inputs

Input	Type	Required	Description
guid	string	yes	Seed for the deterministic RNG.
config	IdenticonConfig	no	Overrides for size, geometry, and palette tuning.

IdenticonConfig

Field	Type	Default	Description
size	number	128	Rendered pixel width/height of the SVG.
head	{ cx, cy, r }	{ 50, 46, 35 }	Head geometry within the 100×100 viewBox.
glasses	{ cx, cy, r }	{ 50, 37, 10 }	Glasses geometry.
mouth	{ cx, cy, w }	{ 50, 65, 13 }	Mouth geometry.
syncedProbability	number	0.7	Probability both eyes share the same gaze direction.
gazeTravelFactor	number	0.32	Pupil travel as a fraction of the glasses radius.
palette	IdenticonPaletteConfig	see below	Color/contrast tuning.

IdenticonPaletteConfig

Field	Type	Default	Description
minBackgroundContrast	number	1.85	Minimum contrast ratio between background and head.
minPairContrast	number	1.38	Minimum contrast ratio between adjacent feature pairs.
hueRange	{ min, max }	{ 35, 320 }	Allowed hue band (default avoids reds).
maxAttempts	number	40	Attempts to find a passing palette before keeping the best.

Framework-agnostic API

The underlying generator is exported for non-component use (SSR, image pipelines, tests):

import { generateAvatar } from 'identicon-angular';

const svgMarkup: string = generateAvatar('some-guid', { size: 64 });

Also exported: createPalette, createRng, resolveConfig, DEFAULT_IDENTICON_CONFIG, and the related types (IdenticonConfig, IdenticonPaletteConfig, ResolvedIdenticonConfig, Palette, Rng).

Development

npm run build   # build the library to dist/
npm test        # run unit tests (Vitest)

License

MIT