JavaScript API

Below is the Jdenticon interface described. Jdenticon will always operate on a hexadecimal hash string of at least 11 characters when rendering an icon. Since version 1.7.0 an implementation of SHA1 is bundled with Jdenticon which will generate a hash for you if a value is specified instead of a hash string.

data-jdenticon-value="icon value" Browser

This HTML attribute can be added to any canvas or svg element. Once the page is loaded, an identicon for the specified value will be rendered in the attributed element. SHA1 will be used to compute a hash of the specified value.

Canvas icons are bitmaps that are scaled on high DPI screens causing a blurry look, while SVG icons are rendered at the native screen resolution ensuring crisp icons. However the performance of SVG rendering varies among the browsers and is generally about twice as slow as canvas rendering. With normal DPI and zoom settings there is no visual difference between SVG and canvas icons.

user127 below is just an example of a value.

Sample code

<canvas width="200" height="200" data-jdenticon-value="user127">
    Fallback text for browsers not supporting canvas
</canvas>

<svg width="200" height="200" data-jdenticon-value="user127">
    Fallback text for browsers not supporting inline svg
</svg>
data-jdenticon-hash="hash" Browser

Works the same way as data-jdenticon-value but takes a precomputed hexadecimal hash string of at least 11 characters. This attribute is handy if you have an already hashed value stored in your database or if you for some reason want to use another hash algorithm than SHA1 for generating the hash.

If both data-jdenticon-value and data-jdenticon-hash is specified on an element data-jdenticon-hash has precedence.

Sample code

<canvas width="200" height="200" data-jdenticon-hash="ff8adece0631821959f443c9d956fc39">
    Fallback text for browsers not supporting canvas
</canvas>

<svg width="200" height="200" data-jdenticon-hash="ff8adece0631821959f443c9d956fc39">
    Fallback text for browsers not supporting inline svg
</svg>
window.jdenticon_config
jdenticon.config
Node.js Browser

The global jdenticon_config variable is used to customize the colors of the generated icons to better fit your website design. This is done by adding the following code block anywhere on your page.

Sample code

<script>

var jdenticon_config = {
    hues: [128],
    lightness: {
        color: [0.4, 0.8],
        grayscale: [0.3, 0.9]
    },
    saturation: {
        color: 0.5,
        grayscale: 0
    },
    backColor: "#fff",
    replaceMode: "once"
};

</script>

Any of the member variables can be omitted, in which case the default values will be used. Any changes to the variables in runtime are affected immediately, but only on icons generated after the time of change.

OptionDefault valueDescription
huesnullLimits the possible hues in generated icons. The hues are specified as an array of hues in degrees. If the option is omitted or an empty array is specified, all hues are allowed. Available since version 2.1.0.
lightness.color[0.4, 0.8]Specifies the lightness range of colored shapes of an icon. The range is expressed as an array containing two numbers, representing the minimum and maximum lightness in the range [0.0, 1.0].
lightness.grayscale[0.3, 0.9]Specifies the lightness range of grayscale shapes of an icon. The range is expressed as an array containing two numbers, representing the minimum and maximum lightness in the range [0.0, 1.0].
saturation.color0.5Specifies the saturation of the originally colored shapes of an icon. The saturation is expressed as a number in the range [0.0, 1.0]. Available since version 2.1.0 and was previously called just saturation.
saturation.grayscale0.0Specifies the saturation of the originally grayscale shapes of an icon. The saturation is expressed as a number in the range [0.0, 1.0]. Available since version 2.1.0.
backColor"#00000000"Specifies the background color to be rendered behind the icon. Supported syntaxes are #rgb, #rgba, #rrggbb and #rrggbbaa. Available since version 2.0.0.
replaceMode"once"Specifies when icons will be rendered. This option has no effect on Node.js. Available since version 2.1.0.
  • "never" – icons are never rendered automatically. You need to call jdenticon.update() manually to render identicons.
  • "once" – icons are rendered once the page has loaded. Any dynamically inserted or modified icons will not be rendered unless jdenticon.update() is manually called.
  • "observe" – icons are rendered upon page load, and the DOM is monitored for new icons using a MutationObserver. Use this if icons are inserted dynamically, e.g. by using Angular, React or VanillaJS. This option behaves as "once" in IE<11.

On Node.js the jdenticon.config variant can be used. This method should be avoided in the browser, at least when loading the library asynchronously, since the config variable might be set before Jdenticon has loaded, leading to a script error.

Sample code

var jdenticon = require("jdenticon");
jdenticon.config = {
    lightness: {
        color: [0.4, 0.8],
        grayscale: [0.3, 0.9]
    },
    hues: [120]
};
jdenticon() Browser

Updates all canvas and SVG elements with the data-jdenticon-value or data-jdenticon-hash attribute. This method is automatically called once the page is loaded but can be called explicitly. Be careful with this function - it will rerender all identicons on the page!

jdenticon.update(element|selector[, hash|value[, padding]])
Browser

Updates the identicon in a specified element. The first parameter element|selector can be either a canvas element, an SVG element or a CSS selector to a canvas or SVG element. If the selector evaluates to multiple elements, all elements are updated.

If the second parameter hash|value contains a hexadecimal string of at least 11 characters it is considered a valid hash and used as base for the icon. If it contains any other value it is hashed using SHA1. If null or undefined is specified, or if the parameter is omitted, the function will in first hand look for a data-jdenticon-hash attribute on the element, in second hand for a data-jdenticon-value attribute.

padding specifies the padding surrounding the icon in percents in the range 0.0 to 0.5. Default is 0.08.

Sample code

<canvas id="identicon" width="100" height="100" />
<script src="jdenticon.min.js"></script>
<script>
    jdenticon.update("#identicon", "ff8adece0631821959f443c9d956fc39");
</script>
jdenticon.drawIcon(ctx, hash|value, size[, padding]) Browser

Renders an indenticon at position (0, 0) with the specified size in pixels on the canvas context specified by the ctx parameter. The second parameter is considered a hash string if the string is hexadecimal and contains at least 11 characters. It is otherwise hashed using SHA1.

padding specifies the padding surrounding the icon in percents in the range 0.0 to 0.5. If the parameter is omitted no padding will be added to the icon. The parameter is available from version 2.0.0.

jdenticon.toSvg(hash|value, size[, padding]) Node.js Browser

Renders an SVG indenticon for the specified hash|value with the specified size in pixels. The first parameter is considered a hash string if the string is hexadecimal and contains at least 11 characters. It is otherwise hashed using SHA1.

padding specifies the padding surrounding the icon in percents in the range 0.0 to 0.5. Default is 0.08.

The response can either be used in the DOM or saved as a file with the *.svg extension. This method does not have any dependencies to the DOM and can be used to generate icons server-side e.g. by using Node.js.

jdenticon.toPng(hash|value, size[, padding]) Node.js

Renders a PNG indenticon for the specified hash|value with the specified size in pixels and returns a Buffer containing the PNG data stream. This method is only intended for Node.js and does not run in the browser.

hash|value is considered a hash string if the string is hexadecimal and contains at least 11 characters. It is otherwise hashed using SHA1.

padding specifies the padding surrounding the icon in percents in the range 0.0 to 0.5. Default is 0.08.

Sample code

var jdenticon = require("jdenticon"),
    fs = require("fs"),
    size = 200,
    value = "icon value",
    png = jdenticon.toPng(value, size);
    
fs.writeFileSync("./testicon.png", png);
$(...).jdenticon([hash[, padding]]) jQuery

Only available if jQuery is loaded before Jdenticon is loaded. Updates all identicons in the collection.

hash|value is considered a hash string if the string is hexadecimal and contains at least 11 characters. It is otherwise hashed using SHA1. If no hash or value is specified, the value of the data-jdenticon-hash or data-jdenticon-value attribute is used.

padding specifies the padding surrounding the icon in percents in the range 0.0 to 0.5. Default is 0.08.