SVG framework function: renderIcon

This tutorial is part of Iconify SVG Framework functions tutorial.

Function renderIcon() generates data used by renderSVG() and renderHTML() functions.

This function is meant to be used when you generate <svg> element yourself. For example, if it is generated by some component.

Usage

Function has the following parameters:

• name, string. Icon name.
• customisations. Optional customizations object.

Function returns object containing icon data, null if icon is not available.

Result

Result object has the following properties:

• attributes, object. List of attributes for <svg> element.
• body, string. Icon contents.

The list of attributes does not include standard attributes: xmlns, xmlns:link. It also does not include attributes that are added by SVG framework: aria-hidden, focusable, role, class, style. It is up to you to decide what attributes you want to add.

Change IDs!

Use function replaceIDs() when generating icons using data provided by this function.

It will make sure elements inside each icon have unique IDs.

Examples

jsIconify.renderIcon('bi:stopwatch', {
   hFlip: true,
   height: '24',
});

Result:

json{
   "attributes": {
       "width": "24",
       "height": "24",
       "preserveAspectRatio": "xMidYMid meet",
       "viewBox": "0 0 16 16"
   },
   "body": "<g transform=\"translate(16 0) scale(-1 1)\"><g fill=\"currentColor\"><path fill-rule=\"evenodd\" d=\"M8 15A6 6 0 1 0 8 3a6 6 0 0 0 0 12zm0 1A7 7 0 1 0 8 2a7 7 0 0 0 0 14z\"/><path fill-rule=\"evenodd\" d=\"M8 4.5a.5.5 0 0 1 .5.5v4a.5.5 0 0 1-.5.5H4.5a.5.5 0 0 1 0-1h3V5a.5.5 0 0 1 .5-.5zM5.5.5A.5.5 0 0 1 6 0h4a.5.5 0 0 1 0 1H6a.5.5 0 0 1-.5-.5z\"/><path d=\"M7 1h2v2H7V1z\"/></g></g>"
}

Another example:

js// Get icon data
const icon = Iconify.renderIcon('carbon:deploy');

// Create element
const svg = document.createElement('svg');
const svgDefaults: IconifySVGProps = {
   'xmlns': 'http://www.w3.org/2000/svg',
   'xmlns:xlink': 'http://www.w3.org/1999/xlink',
   'aria-hidden': true,
   'focusable': false,
   'role': 'img',
};
Object.keys(svgDefaults).forEach((attr) => {
   svg.setAttribute(attr, svgDefaults[attr]);
});
Object.keys(icon.attributes).forEach((attr) => {
   svg.setAttribute(attr, icon.attributes[attr]);
});

// Set content
svg.innerHTML = Iconify.replaceIDs(icon.body);

Customizations

Second parameter is optional icon customizations. Do not confuse it with placeholder data- attributes.

Available customizations:

IconifyIconCustomisations type is an object with the following optional properties, split into several categories.

Vertical alignment:

• inline, boolean. If enabled, adds vertical-align: -0.125em to style, rendering icon below baseline. The default value is false.

Icon dimensions:

• width, string|number|null. Icon width. The default value is null.
• height, string|number|null. Icon height. The default value is null.

There are several keywords that can be used for width and height:

• "auto" sets dimension to original icon's dimensions found in viewBox.
• "unset" and "none" remove dimensions from SVG.

If neither of dimensions is set, height defaults to "1em".

It is enough to set one dimension, such as height. Another dimension will be calculated using icon's width/height ratio. In the case of keywords, another dimension will be set to the same keyword.

Transformations:

• hFlip, boolean. Flip icon horizontally. The default value is false.
• vFlip, boolean. Flip icon vertically. The default value is false.
• rotate, number. Rotation in 90 degrees increments. The default value is 0.

For more details about dimensions and alignment see icon dimensions documentation.

For more details about transformations see icon transformations documentation.

Rendering SVG or HTML

This function creates object. If you want to create <svg> element, use renderSVG() instead. If you want to get HTML string, use renderHTML() instead.