{"id":11135,"library":"jdenticon","title":"Jdenticon","description":"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.","status":"active","version":"3.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/dmester/jdenticon","tags":["javascript","identicon","jdenticon","avatar","typescript"],"install":[{"cmd":"npm install jdenticon","lang":"bash","label":"npm"},{"cmd":"yarn add jdenticon","lang":"bash","label":"yarn"},{"cmd":"pnpm add jdenticon","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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`).","wrong":"const jdenticon = require('jdenticon'); jdenticon.update();","symbol":"update","correct":"import { update } from 'jdenticon';"},{"note":"Jdenticon uses named exports for its primary API functions. Attempting a default import will result in `undefined` for `drawIcon`.","wrong":"import jdenticon from 'jdenticon'; jdenticon.drawIcon(...);","symbol":"drawIcon","correct":"import { drawIcon } from 'jdenticon';"},{"note":"The `toPng` function, used for server-side PNG generation, is specifically exported from the Node.js bundle to ensure correct dependencies and environment assumptions.","wrong":"import { toPng } from 'jdenticon';","symbol":"toPng","correct":"import { toPng } from 'jdenticon/node';"},{"note":"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.","symbol":"Standalone auto-rendering","correct":"import 'jdenticon/standalone';"}],"quickstart":{"code":"import { update } from 'jdenticon';\n\ndocument.addEventListener('DOMContentLoaded', () => {\n  // Assume HTML elements with data-jdenticon-value are present\n  // e.g., <svg width=\"80\" height=\"80\" data-jdenticon-value=\"my-icon-seed\"></svg>\n  // or <canvas width=\"80\" height=\"80\" data-jdenticon-value=\"my-icon-seed\"></canvas>\n\n  // To render all icons on the page with data-jdenticon-value attribute:\n  update();\n\n  // To dynamically create and render an icon on a specific element:\n  const svgElement = document.createElement('svg');\n  svgElement.setAttribute('width', '100');\n  svgElement.setAttribute('height', '100');\n  // The `update` function can take an element and a value\n  update(svgElement, 'dynamic-icon-seed');\n  document.body.appendChild(svgElement);\n\n  // Example of using a specific value for an existing element:\n  const existingCanvas = document.querySelector('canvas[data-jdenticon-value=\"icon value\"]');\n  if (existingCanvas) {\n    update(existingCanvas, 'new-seed-for-canvas');\n  }\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Call `jdenticon.update()` after DOM content is loaded, or `import 'jdenticon/standalone'` instead of `jdenticon` if you prefer the old automatic rendering behavior.","message":"Starting 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"If you relied on zero padding for `drawIcon`, explicitly pass `{ padding: 0 }` as part of the config object to the `drawIcon` method.","message":"In v3.0.0, the default `padding` for the `drawIcon` method was changed from `0` to `0.08` to improve visual consistency.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update your configuration to use the nested `saturation.color` and `saturation.grayscale` properties for finer control over saturation settings.","message":"Directly setting `jdenticon_config.saturation` is deprecated since v2.1.0. Use `jdenticon_config.saturation.color` or `jdenticon_config.saturation.grayscale` instead.","severity":"deprecated","affected_versions":">=2.1.0"},{"fix":"For browser-specific code: `import { update } from 'jdenticon/browser';`. For Node.js-specific code: `import { toPng } from 'jdenticon/node';`.","message":"When 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.","severity":"gotcha","affected_versions":">=3.2.0"},{"fix":"Ensure you are on Jdenticon v3.0.1 or later. If issues persist, review your `tsconfig.json` `lib` array and `typeRoots`.","message":"Older 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.","severity":"gotcha","affected_versions":">=3.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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()`.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'update')"},{"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'`.","cause":"The module resolver (e.g., Webpack, TypeScript) cannot locate the package or is configured incorrectly for your environment (browser vs. Node.js).","error":"Module not found: Can't resolve 'jdenticon'"},{"fix":"Explicitly import `toPng` from the Node.js specific bundle: `import { toPng } from 'jdenticon/node';`.","cause":"The `toPng` function is specific to the Node.js environment and is not part of the main (browser-oriented) `jdenticon` export.","error":"Property 'toPng' does not exist on type 'typeof import(\"jdenticon\")'."},{"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.","cause":"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`.","error":"Error: Jdenticon: Canvas element must be passed when rendering on Node.js."}],"ecosystem":"npm"}