jdenticon.configure()

Sets a configuration object used to customize the look of generated icons, and to modify the behavior of Jdenticon. If jdenticon.configure() is called without an argument, the current global configuration object is returned.

window.jdenticon_config = { };
jdenticon.configure({ });

Properties

	Option	Default value	Description
	hues	null	(from v2.1.0) Limits 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.
	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.color	0.5	(from v2.1.0) Specifies the saturation of the originally colored shapes of an icon. The saturation is expressed as a number in the range [0.0, 1.0]. Was previously called just saturation.
	saturation.grayscale	0.0	(from v2.1.0) Specifies the saturation of the originally grayscale shapes of an icon. The saturation is expressed as a number in the range [0.0, 1.0].
	backColor	"#00000000"	(from v2.0.0) Specifies the background color to be rendered behind the icon. Supported syntaxes are #rgb, #rgba, #rrggbb and #rrggbbaa.
	padding	0.08	(from v2.2.0) Specifies the padding surrounding the icon in percents in the range 0.0 to 0.5. Additional padding might be inserted by Jdenticon to ensure the icon is aligned to the pixel grid.
	replaceMode	"once"	(from v2.1.0) Specifies when icons will be rendered. This option has no effect on Node.js or in module builds of Jdenticon. "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 three ways of specifying a configuration object (in order of resolution):

1. (from v2.2.0) Parameter to jdenticon.drawIcon(), jdenticon.update(), jdenticon.updateSvg(), jdenticon.updateCanvas(), jdenticon.toPng() or jdenticon.toSvg(). This is suitable when using a module loader and you don't want to modify the global configuration.
2. Method jdenticon.configure({}) is suitable for Node.js based environments, when Jdenticon is loaded as an ES module, or when a browser bundler like Webpack or Rollup is used. Note that this approach will cause a reference error in browser environments if this method is called before the Jdenticon library is loaded.
3. Global variable window.jdenticon_config is suitable for browsers and should be assigned before the Jdenticon library is included.

The default configuration object 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",
    padding: 0.08,
    replaceMode: "once"
};

</script>
<script src="https://cdn.jsdelivr.net/npm/jdenticon@3.2.0/dist/jdenticon.min.js" async
        integrity="sha384-yBhgDqxM50qJV5JPdayci8wCfooqvhFYbIKhv0hTtLvfeeyJMJCscRfFNKIxt43M"
        crossorigin="anonymous">
</script>

On Node.js the jdenticon.configure method can be used. This method is also appropriate when Jdenticon is loaded with a bundler like Webpack or Rollup.

Usage on Node.js

const jdenticon = require("jdenticon");

jdenticon.configure({
    lightness: {
        color: [0.4, 0.8],
        grayscale: [0.3, 0.9]
    },
    hues: [120],
    padding: 0.08
});
jdenticon.toSvg("icon value", 100);

To avoid side effects you can also pass a configuraton object directly to an API method.

Passing config to API method

const jdenticon = require("jdenticon");

jdenticon.toSvg("icon value", 100, {
    lightness: {
        color: [0.4, 0.8],
        grayscale: [0.3, 0.9]
    },
    hues: [120],
    padding: 0.08
});