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>
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) 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.

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.

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 = {
    lightness: {
        color: [0.4, 0.8],
        grayscale: [0.3, 0.9]
    },
    saturation: 0.5
};

</script>

Any of the member variables can be omitted, in which case the default values above will be used. color specifies the lightness range of the colored shapes in generated indenticons, and grayscale the lightness range of non-colored shapes. The range can be inverted (e.g. [0.6, 0.3]) to invert light and dark colored shapes. saturation only affects the saturation of colored shapes. All values are specified in the range [0.0, 1.0]. Any changes to the variables in runtime are affected immediately, but only on icons generated after the time of change.

On Node.js the jdenticon.config variant could 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]
    },
    saturation: 0.5
};