Iconify Utils

Iconify Utils is a set of reusable functions that are used by various Iconify icon components and related packages:

• Parsing Iconify icon sets in IconifyJSON format.
• Exporting icons from IconifyIcon format (can be extracted from an icon set) as SVG.
• Basic parser for SVG.
• Parsing and validating icon names.
• Parsing and validating basic colors.
• Parsing emoji sequences, generating regular expressions to find emojis in text.

Library is written in TypeScript, is available as ES modules for modern development and CommonJS for older scripts.

Installation

To install library run:

npm install @iconify/utils --save

Examples

Documentation for each function below includes code samples.

In addition to that, there are several bigger code samples for specific commonly used tasks to help you figure out what functions to use.

Functions

Icon sets are stored in IconifyJSON format. Functions for working with icon sets:

• validateIconSet(data) validates an icon set. If you are not sure if the source is a valid icon set, run this function to validate an icon set. It will convert data to correct IconifyJSON and will attempt to fix errors.
• quicklyValidateIconSet(data) same as above, but does basic validation. Use it if you do not care about metadata being invalid, if you do not want to attempt to fix errors in an icon set, or if you want to reduce bundle size.
• getIcons(data, icons) extracts few icons from an icon set. It can be used to reduce an icon set to few icons that are used by your project.
• getIconData(data, icon) extracts data for one icon from an icon set.
• minifyIconSet(data) minifies icon set, removing redundant data. Used to reduce file size.
• expandIconSet(data) is the opposite of function above.
• convertIconSetInfo(data) converts a legacy icon set format to correct IconifyInfo type.
• parseIconSet(data, callback) parses icon set, calling callback function for every icon. Can be used to extract all icons from an icon set. Validate icon set before parsing it.
• parseIconSetAsync(data, callback) is async version of parseIconSet(), where both function and callback are asynchronous.

Functions for working with IconifyIcon format that represents one icon:

• mergeIconData(icon, alias) merges data for icon and alias. Used by functions that extract icon data from an icon set.
• defaultIconProps contains default values for optional properties to IconifyIcon object.
• convertParsedSVG(data) can be used to convert SVG string to IconifyIcon object.

When rendering icon, customisations can be applied to it. For example, changing dimensions, rotating or flipping icon. They are represented by IconCustomisations type. Functions for working with customisations:

• mergeCustomisations(defaultIconCustomisations, custom) function converts an object to FullIconCustomisations type. It also validates types, so it can be used to clean up user input.
• defaultIconCustomisations exported from lib/customisations/defaults contains default customisations.
• toBoolean(name, value, defaultValue) converts various strings to boolean. Used by icon components to clean up parameters that can be boolean or string.
• rotateFromString(value) converts various methods of rotating icon (such as "90deg" or "25%") to a number.
• flipFromString(customisations, value) applies flip string (such as flip="horizontal,vertical") to customisations.

Functions for rendering icon:

• iconToSVG(icon, customisations) generates data needed to render SVG. It does not generate full SVG, only content and list of attributes to add to the SVG element, making it easy to use in custom components.
• iconToHTML(body, attributes) converts result of iconToSVG() to SVG string.
• calculateSize(size, ratio) calculates icon dimensions. It is used when building icons using iconToSVG().
• replaceIDs(content) replaces IDs in SVG with unique IDs. IDs used in elements like masks, and they must be unique, so multiple icons displayed on the same page using the same IDs will result in chaos. This function prevents that chaos.
• getIconCSS(icon) generates stylesheet for using icon as background image or mask image.
• getIconsCSS(iconSet, names) generates stylesheet for using multiple icons from the same icon set as background images or mask images.
• getIconContentCSS(icon, options) generates stylesheet for using icon as content of pseudo-element.
• getIconsContentCSS(iconSet, names, options) generates stylesheet for using multiple icons from the same icon set as content of pseudo-elements.
• cleanUpInnerHTML() allows using innerHTML to assign SVG to an existing DOM element in strict environments.

Functions for parsing icons:

• parseSVGContent(content) parses SVG string, extracting <svg> attributes and body.
• buildParsedSVG(data) converts result of parseSVGContent(content) to the same data as generated by iconToSVG().
• convertParsedSVG(data) converts result of parseSVGContent(content) to IconifyIcon object.
• splitSVGDefs(content) split icon content in definitions and other data. It is used by wrapSVGContent().
• mergeDefsAndContent(defs, content) merges back definitions and content in one string.
• wrapSVGContent(body, start, end) wraps icon content, without wrapping definition. It is used to wrap content in groups by various functions.
• getSVGViewBox(value) parses and validates viewBox attribute, returning it as an array of numbers on success, undefined on error.

Functions for working with icon names:

• matchIconName constant is a regular expression to test parts of icon name.
• stringToIcon(value) converts icon name, such as "mdi-light:home" into an IconifyIconName object and optionally validates it.
• validateIconName(icon) validates IconifyIconName object.

Functions for working with colors:

• stringToColor(value) converts string to Color object, returns null on error. This can be used to validate user input. It supports color keywords, hexadecimal colors, RGB, HSL, LAB and LCH colors. Variables are not supported because this is meant for parsing SVGs, which should not reference any external variables.
• compareColors(color1, color2) compares colors. It also converts RGB to HSL if needed.
• colorToString(color) converts Color object to string. Combined with stringToColor(), this can be used to validate and clean up user input.

Advanced usage

Iconify Utils can do only basic parsing of IconifyJSON and IconifyIcon data. It is not meant for more complex stuff.

For more complex stuff, such as importing icons, validating icon code, changing palette, cleaning up, exporting to various formats, see Iconify Tools package.