Iconify Utils is a set of reusable functions that are used by various Iconify icon components and related packages:
- Parsing Iconify icon sets in format.
- Exporting icons from 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.
To install library run:
npm install @iconify/utils --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 informat. Functions for working with icon sets:
- 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 and will attempt to fix errors.
- 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.
- 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.
- extracts data for one icon from an icon set.
- minifies icon set, removing redundant data. Used to reduce file size.
- is the opposite of function above.
- converts a legacy icon set format to correct type.
- 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.
- is async version of , where both function and callback are asynchronous.
Functions for working withformat that represents one icon:
- merges data for icon and alias. Used by functions that extract icon data from an icon set.
- contains default values for optional properties to object.
- can be used to convert SVG string to object.
When rendering icon, customisations can be applied to it. For example, changing dimensions, rotating or flipping icon. They are represented bytype. Functions for working with customisations:
- function converts an object to type. It also validates types, so it can be used to clean up user input.
- exported from lib/customisations/defaults contains default customisations.
- converts various strings to boolean. Used by icon components to clean up parameters that can be boolean or string.
- converts various methods of rotating icon (such as "90deg" or "25%") to a number.
- applies flip string (such as flip="horizontal,vertical") to customisations.
Functions for rendering icon:
- 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.
- converts result of to SVG string.
- calculates icon dimensions. It is used when building icons using .
- 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.
- generates stylesheet for using icon as background image or mask image.
- generates stylesheet for using multiple icons from the same icon set as background images or mask images.
- generates stylesheet for using icon as content of pseudo-element.
- generates stylesheet for using multiple icons from the same icon set as content of pseudo-elements.
- allows using innerHTML to assign SVG to an existing DOM element in strict environments.
Functions for parsing icons:
- parses SVG string, extracting attributes and body.
- converts result of to the same data as generated by .
- converts result of to object.
- split icon content in definitions and other data. It is used by .
- merges back definitions and content in one string.
- wraps icon content, without wrapping definition. It is used to wrap content in groups by various functions.
- parses and validates viewBox attribute, returning it as an array of numbers on success, on error.
Functions for working with icon names:
- constant is a regular expression to test parts of icon name.
- converts icon name, such as "mdi-light:home" into an object and optionally validates it.
- validates object.
Functions for working with colors:
- converts string to 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.
- compares colors. It also converts RGB to HSL if needed.
- converts object to string. Combined with , this can be used to validate and clean up user input.
Iconify Utils can do only basic parsing ofand 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.