Usage

There are two ways of using SVG framework functions:

• By using Iconify global.
• By importing Iconify from @iconify/iconify@beta if you are bundling SVG framework with your scripts.

Examples of using loadIcons function:

Even if you use bundle (method shown in second example), Iconify global is also available because SVG framework exports functions and creates a global variable regardless of how you use it. That means you can use method shown in first example regardless of how you import SVG framework.

Functions

Functions are split in several groups:

• General functions.
• Getting icons.
• Adding icons.
• Rendering icons.
• Scanning and observing DOM.
• API functions.
• Internal functions.

Click function name to see more details and examples.

General functions

In this section there is only one function:

• getVersion(). This function returns SVG framework version string. "2.0.0-rc.1"

Getting icons

There are several functions in this section:

• iconExists(name). Checks if an icon exists, returns boolean.
• listIcons(). Lists available icons, returns string[].
• getIcon(name). Returns icon data, returns IconifyIcon object.

Adding icons

Functions for adding icons to SVG framework:

• addIcon(). Adds one icon.
• addCollection(). Adds an icon set.

Note: icons added to SVG framework with these functions are not stored in cache. SVG framework caches only icons retrieved from API.

Rendering icons

Functions that generate SVG or data:

• renderSVG(name, customisations?). Creates <svg> element.
• renderHTML(name, customisations?). Returns <svg> string.
• renderIcon(name, customisations?). Generates data used by functions above. This can be used if you prefer to generate <svg> yourself. Data includes attributes for <svg> and inner HTML.

This section also includes helper function:

• replaceIDs(html). Randomizes IDs in generated string. This should be used when rendering data returned by renderIcon() to make sure elements inside each icon have unique IDs. This function is not needed for icons generated by renderSVG() and renderHTML().

Scanning and observing DOM

SVG framework automatically scans DOM whenever something changes. However, there are some limitations:

• Observer can observe only child elements of document.body.
• SVG framework scans DOM after every change (though scans are throttled to avoid scanning too often).

In some instances you might want to temporarily disable observer or scan an element that is not part of DOM, such as Shadow DOM. There are functions that you can use:

• scan(root?). Scans DOM or custom element for placeholder elements.
• observe(root). Observes custom root element.
• stopObserving(root). Stops observing custom root element. You can call it with document.body as parameter to stop observing document.body.
• pauseObserver(root?). Pauses observer.
• resumeObserver(root?). Resumes observer.

API functions

These functions are not available in module without API.

• loadIcons(icons, callback?). Loads icons from API, calls optional callback when either all or part of icons have been loaded.
• enableCache(). Enables caching in localStorage and sessionStorage.
• disableCache(). Disables caching in localStorage and sessionStorage.
• addAPIProvider(). Adds custom API provider. This is experimental function. API provider functionality is in development.

Internal functions

There are several internal functions that are exposed. They are intended to be used by implementations that want more control over SVG framework, such as Iconify Icon Finder. Use them carefully.

All internal functions are exposed as properties of Iconify._internal object.

Function available with all packages:

• calculateSize(). Calculates icon size. It is used to calculate width if only height is set and vice versa.

Functions available only when API is included:

• getAPI(). Returns internal API module.
• getAPIConfig(). Returns API configuration.
• setAPIModule(provider). Sets API module for provider. This is experimental function intended for custom API providers. API provider functionality is in development.