Iconify Utils

Iconify Utils is a set of reusable functions for working with icon sets and icon data.

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@next --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 icon set. If you are not sure if source is a valid icon set, run this function to validate 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 icon set, or if you want to reduce bundle size.
  • getIcons(data, icons) extracts few icons from icon set. Can be used to reduce icon set to few icons that are used by your project.
  • getIconData(data, icon) extracts data for one icon from 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 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 icon set. Validate icon set before parsing it.

Functions for working with IconifyIcon format that represents one icon:

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:

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 SVG element, making it easy to use in custom components.
  • 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 same IDs will result in chaos. This function prevents that chaos.

Functions for working with icon names:

There are also reusable functions for working with colors. They do not really belong to this package, however, they are used by few projects and making a separate package just for colors did not make much sense, so these functions were moved to Iconify Utils package:

  • 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 is a basic package that parses 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.