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