Iconify SVG framework

This documentation is for Iconify SVG framework version 2 that is currently in beta.

Documentation stable version 1.0 is available here.

Iconify SVG framework is a modern replacement for icon fonts.

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, 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 HTML document is very simple:

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

<script src="https://code.iconify.design/2/2.0.0-rc.2/iconify.min.js"></script>

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

<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-regular: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@beta as dependency and import it in your project:

import 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.

However, SVG framework can also work without API. It allows using Iconify SVG framework in offline web applications.

See using SVG framework without API tutorial.

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?

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.

SPAN 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.

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

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

Dimensions and alignment

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:

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

For various ways to change icon dimensions and alignment, 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.