Iconify SVG framework

There is a new replacement for SVG Framework: Iconify Icon web component.

Please consider migrating to web component.

SVG framework is no longer maintained. It works fine, so it is safe to keep it in an existing project, but should not be used in new projects.

Iconify SVG framework is an easy-to-use JavaScript library that renders icons.

It combines the pixel-perfect rendering of SVG with ease of use of glyph fonts while offering more choice than any glyph font or SVG framework.

Unlike icon fonts, the Iconify SVG framework only loads icons that are used on the current page, so visitors do not waste bandwidth loading hundreds or thousands of icons just to show a few icons.

Iconify SVG framework was designed to be as easy to use as possible. You can change icon dimensions and color with CSS, just like icon fonts.

Usage

Adding icons to the HTML document is easy:

Add script tag to include the Iconify SVG framework. You can add it in the head section (before </head>) or at the end of page before </body>:

html<script src="https://code.iconify.design/3/3.1.1/iconify.min.js"></script>

To add an icon, write placeholder <span> (or it could be any other inline DOM element):

html<span class="iconify-inline" data-icon="fa-solid:home"></span>

To change an icon, write a different icon name in the data-icon attribute instead of "fa-solid:home".

Look in icon collections to find icons. Click an icon to see HTML code for that icon.

Importing SVG framework

You can also import Iconify SVG framework in other script and bundle it with your code. This is useful if you are using tools like WebPack or Rollup.js to build your project.

Install @iconify/iconify as dependency and import it in your project:

jsimport Iconify from '@iconify/iconify';

Usage without API

Iconify SVG framework retrieves icon data from Iconify API. That makes it very easy to use because developer does not need to prepare the icon data. Downside is, visitor must be online to retrieve icon data.

How does it work?

Iconify SVG framework works by locating icon placeholders, retrieving icon name from placeholder, retrieving icon data from Iconify API, then replacing the placeholder with SVG. This is done very quickly in a fraction of a second.

What are the advantages of this approach?

• It is very easy to use, just like icon fonts.
• No need to embed icons in HTML code. Icons retrieved from Iconify API are cached, so they are retrieved only once. If you embed SVG into HTML code, you need to send it to the visitor on every page view.
• Only icons that are found on the current page are retrieved from API. Other SVG frameworks and icon fonts load entire icon sets, wasting your visitor's bandwidth.

What are the disadvantages?

• It requires an internet connection.
• By using public API, you rely on a third party service. However, there is an option to host your own Iconify API, see Iconify API hosting tutorial.

If you need to render icons without relying on Iconify API, use a different icon component.

Icon syntax

An element must have <span> or <i> tag.

For the Iconify SVG framework to treat the element as icon placeholder, the element must have "iconify" or "iconify-inline" among the list of classes.

Element also must have a data-icon attribute with icon name as value.

htmlSPAN or I tag with class="iconify-inline" and data-icon:
<span class="iconify-inline" data-icon="fa-solid:home"></span>
<i class="iconify-inline" data-icon="mdi-account-off"></i><br />

SPAN or I tag with class="iconify" and data-icon:
<span
   class="iconify some-custom-class"
   data-icon="flat-color-icons:cancel"
></span>
<i class="iconify" data-icon="mdi:account-off"></i>

SPAN or I tag with class="iconify-inline" and data-icon:
SPAN or I tag with class="iconify" and data-icon:

Icon name syntax is data-icon="prefix:icon-name" or data-icon="prefix-icon-name". Second syntax can be used if prefix does not contain "-", it is kept for compatibility with icon fonts.

For example, data-icon="fa-arrow-left" and data-icon="fa:arrow-left" are identical (both have a prefix "fa"), but data-icon="flat-color-icons:voice-presentation" and data-icon="flat-color-icons-voice-presentation" are not the same (first has a prefix "flat-color-icons", second has a prefix "flat" that does not exist).

Color

You can only change color of monotone icons. Some icons, such as emoji, have a hardcoded palette that cannot be changed.

To add color to the monotone icon simply change text color.

html<span class="iconify" data-icon="ion:umbrella-sharp" style="color: red"></span>

For various ways to set color, see changing icon color tutorial.

Dimensions

By default, icon height is set to "1em", icon width is changed dynamically based on the icon's width to height ratio.

This makes it easy to change icon size by changing font-size in the stylesheet, just like icon fonts:

html<span
   class="iconify"
   data-icon="cil:locomotive"
   style="font-size: 24px;"
></span>

For various ways to change icon dimensions, see changing icon dimensions tutorial.

Transformations

An icon can be rotated and flipped horizontally and/or vertically. All transformations are done relative to the center of the icon.

These are not CSS transformations, transformations are applied inside SVG.

For more details see icon transformations tutorial.

Functions

Iconify SVG framework offers many functions, which developers can use to control SVG framework:

• Load icons from API.
• Add custom icons and icon sets.
• Generate SVG.
• Control MutationObserver.
• ...and many other functions.

For more details see Iconify SVG framework functions.

Server side rendering

SVG Framework can be used in Node.js scripts, but because there is no DOM, it can be used only to generate data using functions such as buildIcon().

Older versions of Node.js do not support Fetch API. It is available in Node.js version 17 using flag "--experimental-fetch", but without it, Fetch API is not available. That means the icon component cannot retrieve icon data from Iconify API when used on a server side in Node.js environment.

How to solve this problem?

1. Install cross-fetch (if you are using CommonJS) or node-fetch (if you are using modules) as dependency.
2. Use internal setFetch() function to set third party Fetch API before using any SVG framework functions.

jsimport Iconify from '@iconify/iconify';
import fetch from 'cross-fetch';
//  import fetch from 'node-fetch';

// Set Fetch API before doing anything
Iconify._api.setFetch(fetch);