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 icon set) as SVG.
- Parsing and validating icon names.
- Parsing and validating 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.
To install library run:
npm install @iconify/utils@next --save
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.
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.
- 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 icon set.
- defaultIconProps contains default values for optional properties 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 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 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 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 same icon set as background images or mask images.
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.
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.