jdenticon

Jdenticon turns any hashable value — a user ID, email address, or arbitrary string — into a distinctive, deterministic identicon. It computes a SHA1 hash of the input and uses that hash to drive a shape, rotation, and color-selection algorithm, producing a symmetric icon that looks the same every time for the same input. The same core generator can render to either SVG (as a string or DOM element) or an HTML5 canvas, and on the server it works headlessly via the canvas-renderer package to output PNG buffers.

The library ships as multiple build targets — CommonJS and ESM builds for Node, module and UMD/standalone builds for browsers, plus a small CLI for generating icons from the command line. A companion jQuery plugin and DOM auto-render mode (via data-jdenticon-value attributes) make it easy to drop into existing pages without a build step, while the programmatic toSvg/toPng/drawIcon APIs suit server-side generation of avatar placeholders at scale.

What You Get

• A deterministic toSvg(value, size, config) / toPng(value, size, config) API that always produces the same icon for the same input value
• Both SVG (string or live DOM <svg>) and HTML5 canvas rendering paths sharing one core icon-generation algorithm
• Server-side PNG generation on Node.js via the canvas-renderer dependency, with no native canvas binding required
• Automatic DOM rendering: any <svg> or <canvas> element with a data-jdenticon-value attribute is rendered and kept in sync via a MutationObserver-based update() call
• A bundled CLI (jdenticon binary) for generating identicon files directly from the command line
• Configurable color theme, padding, and saturation/lightness ranges via a global or per-call configuration object

Common Use Cases

• Placeholder avatars for users who haven’t uploaded a profile picture
• Visual fingerprints for API keys, commit hashes, or other opaque identifiers so users can spot changes at a glance
• Generating avatar images server-side (Node.js) for emails, exports, or APIs where no browser DOM is available
• Adding auto-updating identicons to a page purely via HTML attributes, without writing any JavaScript
• Batch-generating icon files from a build script or CI job using the bundled CLI

Under The Hood

Architecture The library is organized around a single renderer-agnostic core: iconGenerator() in src/renderer/iconGenerator.js takes a Renderer implementation and a hash string, then deterministically derives shape indexes, rotations, and a color palette purely from slices of the hash (via parseHex), delegating actual drawing calls (beginShape/endShape/setBackground) to whichever renderer was passed in. Two renderer implementations — SvgRenderer (backed by SvgWriter/SvgElement for string or live-DOM output) and CanvasRenderer (backed by the external canvas-renderer package for Node or the native CanvasRenderingContext2D in browsers) — satisfy that interface, so the same generation logic produces pixel-consistent SVG and raster output. A thin src/apis/ layer (toSvg.js, toPng.js, drawIcon.js, update.js, configure.js, jquery.js) exposes the public surface and wires in DOM auto-rendering via a shared MutationObserver in observer.js; changing the core hash-to-shape mapping would alter the visual output of every existing identicon, so that logic is deliberately isolated and untouched across releases for backward compatibility.

Tech Stack Jdenticon is plain, dependency-light JavaScript (compiled through TypeScript 3/4 for type-checking and Buble for down-leveling) with a single runtime dependency, canvas-renderer, used only for the Node.js PNG path. The build is orchestrated by Gulp and Rollup, producing five distinct output artifacts declared in package.json exports — Node CJS/ESM, browser module CJS/ESM, and a UMD standalone bundle for direct <script> inclusion or jsDelivr/unpkg — plus hand-written .d.ts type declarations tested against multiple TypeScript versions and module-resolution modes. There is no framework dependency; it targets plain DOM APIs, HTMLCanvasElement, and Node’s fs/process for the CLI.

Code Quality The project uses tap for unit tests (e.g. a large table-driven SHA1 test suite in test/unit/sha1.js covering block-boundary edge cases) and an extensive matrix of end-to-end tests under test/e2e exercising real browsers (Chrome/Firefox/Safari/Edge/IE via Selenium), Webpack 4/5, and Rollup consumption, alongside a separate test:types suite that compiles sample projects against the shipped .d.ts files under several TypeScript versions. Source files carry consistent JSDoc annotations for parameters and return types, ESLint is configured for the src/ tree, and GitHub Actions runs the test suite on each push. No dedicated CONTRIBUTING guide or docs/ folder ships in the repository itself, though usage documentation is hosted externally at jdenticon.com.

What Makes It Unique Rather than the common grid-of-random-squares identicon pattern, Jdenticon uses a fixed symmetric layout (sides, corners, center) with hash-driven shape selection, per-shape rotation, and a curated color-theme algorithm that avoids visually poor combinations (e.g. dark-gray-on-dark-color), giving its icons a more polished, consistently readable look across many generated values. Its dual-renderer design lets the exact same generation algorithm target SVG or canvas/PNG output — including headless Node.js rendering with no native canvas binding required — which is comprehensive compared to many identicon libraries that only target the browser.