@nimiq/iqons

Nimiq Iqons

SVG+JS Identicons designed to run in browsers and NodeJS. The library is heavily optimized for performance.

See the Iqons in action here.

• Installation
  • Browsers
  • NodeJS
• Usage
• Demos

Installation

Nimiq Iqons can be used in both browsers and NodeJS:

Browsers

You can either use the Iqons script already bundled with the image data (default), or with an external SVG file which is loaded separately.

The Iqons script is provided as an ES6 module and needs to be imported into module scripts or used with build systems such as Webpack and Rollup:

• npm install --save @nimiq/iqons or yarn add @nimiq/iqons
• import Iqons from '@nimiq/iqons'
• See how to use it under Usage

To use the other version of the library, which loads the image data separately, you have to import Iqons from '@nimiq/iqons/dist/iqons.min.js' instead. Additionally you have to make sure that the iqons.min.svg file included in the dist directory of this package is made available to website visitors. Then specify the path where the library can find this SVG file, either by setting Iqons.svgPath = '/public/path/to/iqons.min.svg' or in the global scope with window.NIMIQ_IQONS_SVG_PATH = '/public/path/to/iqons.min.svg'.

Note: Besides installing the package yourself, you can also use a npm-enabled CDN: import Iqons from https://unpkg.com/@nimiq/iqons@1.4/dist/iqons.bundle.min.js.

NodeJS

For NodeJS a CommonJS module is provided, which can simply be installed and used by doing:

• npm install --save @nimiq/iqons or yarn add @nimiq/iqons
• const Iqons = require('@nimiq/iqons').default (the .default is important!)
• See how to use it under Usage

If you are using a version of NodeJS with import enabled, or are using an ES6 loader such as esm or babel-register, you can just do import Iqons from '@nimiq/iqons' for step 2.

Usage

All methods generating identicons are async and return promises.

Get a raw SVG text string:

    const svg = await Iqons.svg(text)

Get a SVG data url string (the one starting with data:image/svg+xml;base64,...), which can be set as img.src:

    const dataUrl = await Iqons.toDataUrl(text)

Render an identicon SVG into the DOM (only in browsers!):

    await Iqons.render(text, element)

Get an <img> DOM node (only in browsers!):

    const img = await Iqons.image(text)

You can generate a placeholder icon with these (sync) methods:

    // Placeholder SVG:
    const svg = Iqons.placeholder(color = '#bbb', strokeWidth = 1)
    // Placeholder data url:
    const dataUrl = Iqons.placeholderToDataUrl(color = '#bbb', strokeWidth = 1)
    // Render placeholder SVG into `element`:
    Iqons.renderPlaceholder(element, color = '#bbb', strokeWidth = 1)

Demos

• Simple demo of custom identicons
• Catalog of all features
• Identicon Builder

Background Info

For more information on our design decisions read our design blog post or watch the Vlog about the beginning of the Iqons.

This is an open source contribution by Nimiq - the browser-based blockchain.