jdenticon.config

A configuration object used to customize the look of generated icons, and to modify the behavior of Jdenticon.

window.jdenticon_config = { };
jdenticon.config = { };
Compability
Browser: Yes Node.js: Yes

Properties

OptionDefault valueDescription
PropertyhuesnullLimits 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.
Propertylightness.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].
Propertylightness.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].
Propertysaturation.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.
Propertysaturation.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.
PropertybackColor"#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.
PropertyreplaceMode"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.

Remarks

There are two ways of specifying the configuration object.

In most cases the default value is null, meaning that the variable should always be assigned a new configuration object to avoid null reference errors.

All configuration properties have default values. Only specify the properties you want to modify. Any changes to the variables in runtime are effective immediately, but only on icons generated after the time of change.

Example

The following example shows how to use the config variable in the browser.

Usage in browsers

<svg width="100" height="100" data-jdenticon-value="Sample icon"></svg>
<script>

window.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>
<script src="https://cdn.jsdelivr.net/npm/jdenticon@2.1.0" async></script>

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.

Usage on Node.js

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