jdenticon

library3.3.0jsnpmunverified

Jdenticon is a JavaScript library for generating unique, recognizable identicons, often used for user avatars or cryptographic hashing visualization. It supports rendering these icons into both HTML5 Canvas (raster) and SVG (vector) elements, providing flexibility for different display needs. The library offers distinct bundles for browser and Node.js environments, enabling client-side display or server-side image generation, including PNG outputs. The current stable version is 3.3.0. Release cadence is somewhat ad-hoc, with several minor releases per year addressing bugs, improving TypeScript support, and enhancing features. Key differentiators include its dual Canvas/SVG rendering capabilities, a wide range of configurable aesthetic properties (padding, saturation, hues), and a CLI tool. Since version 3.0.0, automatic icon rendering on page load requires explicit opt-in.

serialization

npm install jdenticon

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JDENTICON

jdenticon

serializationjavascriptv3.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

update

✓ import { update } from 'jdenticon';

✗ const jdenticon = require('jdenticon'); jdenticon.update();

For ESM modules, named imports are standard. CommonJS `require` works but may pull an incorrect bundle in certain bundler/Node.js configurations without explicit subpath imports (e.g., `jdenticon/node`).

drawIcon

✓ import { drawIcon } from 'jdenticon';

✗ import jdenticon from 'jdenticon'; jdenticon.drawIcon(...);

Jdenticon uses named exports for its primary API functions. Attempting a default import will result in `undefined` for `drawIcon`.

toPng

✓ import { toPng } from 'jdenticon/node';

✗ import { toPng } from 'jdenticon';

The `toPng` function, used for server-side PNG generation, is specifically exported from the Node.js bundle to ensure correct dependencies and environment assumptions.

Standalone auto-rendering

✓ import 'jdenticon/standalone';

Since v3.0.0, automatic icon rendering on page load is disabled by default for the main 'jdenticon' import. To restore the pre-v3 auto-rendering behavior, explicitly import the 'standalone' bundle.

Demonstrates how to import and use Jdenticon to render icons on page load and dynamically create/update icons, accounting for v3.0.0 breaking changes.

import { update } from 'jdenticon'; document.addEventListener('DOMContentLoaded', () => { // Assume HTML elements with data-jdenticon-value are present // e.g., <svg width="80" height="80" data-jdenticon-value="my-icon-seed"></svg> // or <canvas width="80" height="80" data-jdenticon-value="my-icon-seed"></canvas> // To render all icons on the page with data-jdenticon-value attribute: update(); // To dynamically create and render an icon on a specific element: const svgElement = document.createElement('svg'); svgElement.setAttribute('width', '100'); svgElement.setAttribute('height', '100'); // The `update` function can take an element and a value update(svgElement, 'dynamic-icon-seed'); document.body.appendChild(svgElement); // Example of using a specific value for an existing element: const existingCanvas = document.querySelector('canvas[data-jdenticon-value="icon value"]'); if (existingCanvas) { update(existingCanvas, 'new-seed-for-canvas'); } });

jdenticon --version

Debug

Known issues

breakingStarting with v3.0.0, the main 'jdenticon' bundle no longer automatically renders icons on page startup. You must explicitly call `update()` or `drawIcon()` from your code to render icons.

fix

Call `jdenticon.update()` after DOM content is loaded, or `import 'jdenticon/standalone'` instead of `jdenticon` if you prefer the old automatic rendering behavior.

affects: >=3.0.0

breakingIn v3.0.0, the default `padding` for the `drawIcon` method was changed from `0` to `0.08` to improve visual consistency.

fix

If you relied on zero padding for `drawIcon`, explicitly pass `{ padding: 0 }` as part of the config object to the `drawIcon` method.

affects: >=3.0.0

deprecatedDirectly setting `jdenticon_config.saturation` is deprecated since v2.1.0. Use `jdenticon_config.saturation.color` or `jdenticon_config.saturation.grayscale` instead.

fix

Update your configuration to use the nested `saturation.color` and `saturation.grayscale` properties for finer control over saturation settings.

affects: >=2.1.0

gotchaWhen using bundlers or TypeScript with Node16 module resolution, you might need to explicitly import specific bundles (`jdenticon/browser` or `jdenticon/node`) to ensure the correct environment-specific code is used.

fix

For browser-specific code: `import { update } from 'jdenticon/browser';`. For Node.js-specific code: `import { toPng } from 'jdenticon/node';`.

affects: >=3.2.0

gotchaOlder TypeScript configurations (pre-v3.0.1) might have required adding `"dom"` to `lib` in `tsconfig.json` or experienced Node typings leaking into browser contexts. These issues were largely addressed in v3.0.1.

fix

Ensure you are on Jdenticon v3.0.1 or later. If issues persist, review your `tsconfig.json` `lib` array and `typeRoots`.

affects: >=3.0.1

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'update')

After v3.0.0, `jdenticon` no longer automatically initializes or exposes top-level methods for direct access via a script tag without explicit import or assignment to a global.

fix

If using a module system, import named exports like `import { update } from 'jdenticon';`. If using a script tag and relying on auto-rendering, ensure you are importing `jdenticon/standalone` or explicitly call `update()`.

Module not found: Can't resolve 'jdenticon'

The module resolver (e.g., Webpack, TypeScript) cannot locate the package or is configured incorrectly for your environment (browser vs. Node.js).

fix

Check your `node_modules` for `jdenticon`. If using a bundler with specific environment targets or Node16 module resolution, try `import 'jdenticon/browser'` or `import 'jdenticon/node'`.

Property 'toPng' does not exist on type 'typeof import("jdenticon")'.

The `toPng` function is specific to the Node.js environment and is not part of the main (browser-oriented) `jdenticon` export.

fix

Explicitly import `toPng` from the Node.js specific bundle: `import { toPng } from 'jdenticon/node';`.

Error: Jdenticon: Canvas element must be passed when rendering on Node.js.

When using `drawIcon` on Node.js, it typically expects a canvas-compatible object (e.g., from `node-canvas`) as the first argument, unlike in the browser where it can automatically find elements based on `data-jdenticon-value`.

fix

Ensure you are passing a valid canvas context or element from a library like `node-canvas` when calling `drawIcon` in a Node.js environment.

Upgrade

Version history

3.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/dmester/jdenticon ↗

packagehttps://www.npmjs.com/package/jdenticon ↗

homepagehttps://jdenticon.com ↗