Web component function: buildIcon

This tutorial is part of Iconify Icon web component tutorial.

Function buildIcon() generates data used by icon component to render icon.

You can use this function to generate <svg> code.

Usage

Function has the following parameters:

  • icon, IconifyIcon. Icon data.
  • customisations. Optional customizations object.

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

You need icon data before you can use this function. See getIcon(), iconExists() and loadIcon() functions.

Result

Result object has the following properties:

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

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

Customizations

Second parameter is optional icon customizations. 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 base line. 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. Other dimension will be calculated using icon's width/height ratio. In case of keywords, other 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 see icon dimensions documentation.

For more details about transformations see icon transformations documentation.

Example

Code:
import { buildIcon } from 'iconify-icon';
import biStopwatch from '@iconify-icons/bi/stopwatch';

buildIcon(biStopwatch, {
   hFlip: true,
   height: '24',
});
Result:
{
   "attributes": {
       "width": "24",
       "height": "24",
       "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>"
}