Iconify SVG framework

This article is for outdated Iconify SVG Framework version 1.0.

Documentation for the latest version 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 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/1/1.0.7/iconify.min.js"></script>

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

<span class="iconify" 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 as dependency and import it in your project:

import Iconify from '@iconify/iconify';

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. However, there is a solution for offline use, see Iconify icon bundles.
  • Relies on third party service. However, there is an option to host your own Iconify API, see self-hosted API.

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.

Icon syntax

An element must have tag other than <svg>. Usually, it is <span>, but you can use any element, for example, <i> or <strong>.

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

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

Any tag with class and data-icon:
<span class="iconify" data-icon="fa-solid:home"></span>
<i class="iconify" data-icon="mdi-account-off"></i>
<strong
   class="iconify some-custom-class"
   data-icon="flat-color-icons:cancel"
>
</strong>
Any tag with class 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:
<div class="light-blue-block">
   All icons inside this div are light blue, including an umbrella icon
   <span class="iconify" data-icon="ion:umbrella-sharp"></span>
   and attachment icon
   <span class="iconify" data-icon="entypo-attachment"></span>
</div>
<div class="orange-block">
   All text and icons inside this div are orange, including a hourglass icon
   <span class="iconify" data-icon="bx:bx-hourglass"></span>
   and a briefcase icon
   <span class="iconify" data-icon="bx:bxs-briefcase-alt"></span>
</div>
<div>Red home icon: <span class="iconify" data-icon="bx:bx-home"></span></div>
<div>
   Icon with palette:
   <span class="iconify" data-icon="noto:paintbrush"></span>
</div>
Stylesheet:
// Change text color for ".orange-block" to #e70
.orange-block {
   color: #e70;
}
// Change all icons inside ".light-blue-block" to #08f
.light-blue-block .iconify {
   color: #08f;
}
// Change icon "bx:bx-home" to #e00
.iconify[data-icon='bx:bx-home'] {
   color: #e00;
}
// Failed attempt to change icon "noto:paintbrush" to #0e0
.iconify[data-icon='noto:paintbrush'] {
   color: #0e0;
}
Demo:
All icons inside this div are light blue, including an umbrella icon and attachment icon
All text and icons inside this div are orange, including a hourglass icon and a briefcase icon
Red home icon:
Icon with palette:

Color only works for icons that do not have a palette. Color in icons that do have a palette, like noto:paintbrush in an example above, cannot be changed.

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:
<div>
   Default font size and 1em locomotive icon:
   <span class="iconify" data-icon="cil:locomotive"></span>
</div>
<div class="bigger-sample">
   Bigger font and 1em paper plane icon:
   <span class="iconify" data-icon="cil:paper-plane"></span>
</div>
<div class="big-icon">
   Default font size for text, 48px font size for a truck icon
   <span class="iconify" data-icon="cil:truck"></span>
</div>
Stylesheet:
// Change font-size for second line
.bigger-sample {
   font-size: 24px;
   line-height: 32px;
}

// Change font-size only for icon inside third line
.big-icon .iconify {
   font-size: 48px;
   line-height: 1em;
}
Demo:
Default font size and 1em locomotive icon:
Bigger font and 1em paper plane icon:
Default font size for text, 48px font size for a truck icon

If you want icon to have specific size instead of "1em", you can change height and/or width by adding data-height and/or data-width attributes.

If only one attribute is set, another attribute will be calculated using the icon's width to height ratio.

HTML:
<div class="alert">
   Red "alert" icon, data-height="48":
   <span class="iconify" data-icon="mdi-alert" data-height="48"></span>
</div>
<div class="highlight-box">
   <hr />
   In examples below icons have red border, so you could see icon dimensions.<br />
   <br />
   Icon with width/height ratio &lt; 1:
   <span class="iconify" data-icon="fa-regular:id-badge"></span><br />
   Same icon with data-width and data-height attributes set to 1em:
   <span
       class="iconify"
       data-icon="fa-regular:id-badge"
       data-width="1em"
       data-height="1em"
   >
</span
   >
<br />
   <br />
   Icon with width/height ratio &gt; 1:
   <span class="iconify" data-icon="fa-regular:handshake"></span><br />
   Same icon with data-width and data-height attributes set to 1em:
   <span
       class="iconify"
       data-icon="fa-regular:handshake"
       data-width="1em"
       data-height="1em"
   >
</span
   >
<br />
</div>
Stylesheet:
// Red color for alert icon
.alert .iconify {
   color: #d00;
   font-size: 24px; // will not change icon size
}

// Show icon size using box-shadow
.highlight-box .iconify {
   box-shadow: 0 0 0 1px #e00;
}
Demo:
Red "alert" icon, data-height="48":

In examples below icons have red border, so you could see icon dimensions.

Icon with width/height ratio < 1:
Same icon with data-width and data-height attributes set to 1em:

Icon with width/height ratio > 1:
Same icon with data-width and data-height attributes set to 1em:

Why is Iconify SVG framework using data- attributes instead of width and height? To make it easier to change icon dimensions by changing only one dimension. You can change width and/or height by adding attributes or in the stylesheet, however, if you set only one attribute, Iconify SVG framework cannot reliably detect width or height change and set another attribute.

When setting width and height in attributes or stylesheet, make sure you set both attributes. Otherwise, bad things happen:

HTML:
<div>
   These icons are supposed to be square, but only one attribute is set in
   stylesheet:
   <span class="iconify set-height" data-icon="mdi:eyedropper"></span>
   <span class="iconify set-width" data-icon="mdi:eyedropper"></span>
</div>
<div>
   If both attributes are set in stylesheet, icon scales correctly:
   <span class="iconify set-height set-width" data-icon="mdi:eyedropper"></span>
</div>
<div>
   These icons are square in modern browsers, but fail in Internet Explorer,
   which is unfortunately still used by enough people to support it. You can use
   this method, but better just avoid it:
   <span class="iconify" data-icon="mdi:eyedropper" height="48"></span>
   <span class="iconify" data-icon="mdi:eyedropper" width="48"></span>
</div>
Stylesheet:
// Show icon size using box-shadow
.iconify {
   box-shadow: 0 0 0 1px #e00;
}

// Set height
.set-height {
   height: 48px;
}

// Set width
.set-width {
   width: 48px;
}
Demo:
These icons are supposed to be square, but only one attribute is set in stylesheet:
If both attributes are set in stylesheet, icon scales correctly:
These icons are square in modern browsers, but fail in Internet Explorer, which is unfortunately still used by enough people to support it. You can use this method, but better just avoid it:

Transformations

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

Flip

To flip an icon, add data-flip attribute:

HTML:
<div>
   No flip:
   <span class="iconify" data-icon="emojione-v1:tear-off-calendar"></span>
</div>
<div>
   Horizontal:
   <span
       class="iconify"
       data-icon="emojione-v1:tear-off-calendar"
       data-flip="horizontal"
   >
</span>
</div>
<div>
   Vertical:
   <span
       class="iconify"
       data-icon="emojione-v1:tear-off-calendar"
       data-flip="vertical"
   >
</span>
</div>
<div>
   Horizontal and vertical:
   <span
       class="iconify"
       data-icon="emojione-v1:tear-off-calendar"
       data-flip="horizontal,vertical"
   >
</span>
   (same as 180&deg; rotation)
</div>
Stylesheet:
Demo:
No flip:
Horizontal:
Vertical:
Horizontal and vertical: (same as 180° rotation)

Possible values:

  • "horizontal": flip icon horizontally.
  • "vertical": flip icon vertically.
  • "horizontal,vertical": flip icon horizontally and vertically.

Rotation

To rotate an icon, add data-rotate attribute:

HTML:
<div>
   No rotation:
   <span class="iconify" data-icon="noto:paintbrush"></span>
</div>
<div>
   90&deg; rotation:
   <span class="iconify" data-icon="noto:paintbrush" data-rotate="90deg"></span>
</div>
<div>
   180&deg; rotation:
   <span class="iconify" data-icon="noto:paintbrush" data-rotate="180deg"></span>
</div>
<div>
   270&deg; rotation:
   <span class="iconify" data-icon="noto:paintbrush" data-rotate="270deg"></span>
</div>
Stylesheet:
Demo:
No rotation:
90° rotation:
180° rotation:
270° rotation:

Rotation can be done by 90°, 180°, and 270°. Why only these angles? Because unlike CSS rotations, icon rotations are done inside an icon and modify the bounding box.

When an icon is rotated by 90° and 270°, the icon's width and height properties are swapped.

Possible values:

  • "90deg", "1": rotate by 90 degrees.
  • "180deg", "2": rotate by 180 degrees.
  • "270deg", "3": rotate by 270 degrees.

Comparison with CSS rotation:

HTML:
<div>
   Original icon:
   <span class="iconify" data-icon="fa:arrows-v"></span>
</div>

<div>
   Icon rotated with data-rotate attribute
   <span class="iconify" data-icon="fa:arrows-v" data-rotate="90deg"></span>
   that keeps 1em height and does not affect text around it.
</div>
<div>
   Icon rotated with CSS
   <span class="iconify rotate" data-icon="fa:arrows-v"></span>
   that does affect text around it because it becomes wider than element's box.
</div>
Stylesheet:
// Show icon size using box-shadow
.iconify {
   box-shadow: 0 0 0 1px #e00;
}

// Rotate icon by 90 degrees
.rotate {
   transform: rotate(90deg) !important;
}
Demo:
Original icon:
Icon rotated with data-rotate attribute that keeps 1em height and does not affect text around it.
Icon rotated with CSS that does affect text around it because it becomes wider than element's box.

You can use both rotation and flip on an icon. The icon is flipped first, then rotated.

Vertical alignment

Many users are switching to Iconify from icon fonts. To make things easier, by default, the Iconify SVG framework behaves like an icon font.

Icon font characters are drawn by browsers like any other font, not like images.

What's the difference?

  • Fonts have the ascend and descend properties, which cause glyphs to render near the baseline.
  • Images are rendered on the baseline.

Because of that difference, when switching from font to images, images appear to render above the text. This can be fixed by adding vertical-align and that's exactly what Iconify SVG framework does by default.

So how to change behaviour?

Inline rendering

To render icon inline, simply write a placeholder using an inline tag, such as <span> or <i>:

An icon <span class="iconify" data-icon="fa-solid:home"></span> aligned like icon font's glyph.
An icon aligned like icon font's glyph.

This will force the Iconify SVG framework to add vertical-align style to <svg> element to align it like icon font glyph:

<svg
   xmlns="http://www.w3.org/2000/svg"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   aria-hidden="true"
   focusable="false"
   width="1.13em"
   height="1em"
   style="vertical-align: -0.125em;-ms-transform: rotate(360deg); -webkit-transform: rotate(360deg); transform: rotate(360deg);"
   preserveAspectRatio="xMidYMid meet"
   viewBox="0 0 576 512"
   class="iconify"
   data-icon="fa-solid:home"
>

   <path
       d="M280.37 148.26L96 300.11V464a16 16 0 0 0 16 16l112.06-.29a16 16 0 0 0 15.92-16V368a16 16 0 0 1 16-16h64a16 16 0 0 1 16 16v95.64a16 16 0 0 0 16 16.05L464 480a16 16 0 0 0 16-16V300L295.67 148.26a12.19 12.19 0 0 0-15.3 0zM571.6 251.47L488 182.56V44.05a12 12 0 0 0-12-12h-56a12 12 0 0 0-12 12v72.61L318.47 43a48 48 0 0 0-61 0L4.34 251.47a12 12 0 0 0-1.6 16.9l25.5 31A12 12 0 0 0 45.15 301l235.22-193.74a12.19 12.19 0 0 1 15.3 0L530.9 301a12 12 0 0 0 16.9-1.6l25.5-31a12 12 0 0 0-1.7-16.93z"
       fill="currentColor"
   >
</path>
</svg>

If you want to understand other attributes added to <svg> by Iconify SVG framework, see SVG rendering section below.

Block rendering

If you want to align icon perfectly, like an image, you need to tell Iconify SVG framework to use block mode.

The only difference between inline and block mode is, for block mode SVG framework does not add vertical-align to <svg>.

There are two ways to force block mode:

  • Adding data-inline="false" attribute.
  • Using <iconify-icon> tag instead of <span>.
<div>
   An icon <span class="iconify" data-icon="fa-solid:home" data-inline="false"></span> aligned like image.
</div>
<div>
   Another icon <iconify-icon data-icon="fa-solid:home"></iconify-icon> using different syntax.
</div>
An icon aligned like image.
Another icon using different syntax.

This will force the Iconify SVG framework to not add vertical-align style to <svg> element, so browsers render it like an image:

<svg
   xmlns="http://www.w3.org/2000/svg"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   aria-hidden="true"
   focusable="false"
   width="1.13em"
   height="1em"
   style="-ms-transform: rotate(360deg); -webkit-transform: rotate(360deg); transform: rotate(360deg);"
   preserveAspectRatio="xMidYMid meet"
   viewBox="0 0 576 512"
   class="iconify"
   data-icon="fa-solid:home"
   data-inline="false"
>

   <path
       d="M280.37 148.26L96 300.11V464a16 16 0 0 0 16 16l112.06-.29a16 16 0 0 0 15.92-16V368a16 16 0 0 1 16-16h64a16 16 0 0 1 16 16v95.64a16 16 0 0 0 16 16.05L464 480a16 16 0 0 0 16-16V300L295.67 148.26a12.19 12.19 0 0 0-15.3 0zM571.6 251.47L488 182.56V44.05a12 12 0 0 0-12-12h-56a12 12 0 0 0-12 12v72.61L318.47 43a48 48 0 0 0-61 0L4.34 251.47a12 12 0 0 0-1.6 16.9l25.5 31A12 12 0 0 0 45.15 301l235.22-193.74a12.19 12.19 0 0 1 15.3 0L530.9 301a12 12 0 0 0 16.9-1.6l25.5-31a12 12 0 0 0-1.7-16.93z"
       fill="currentColor"
   >
</path>
</svg>

If you want to understand other attributes added to <svg> by Iconify SVG framework, see SVG rendering section below.

SVG rendering

The Iconify SVG framework changes SVG a little to make it behave like the icon fonts and to account for browser bugs.

An example of a rendered SVG:

<svg
   xmlns="http://www.w3.org/2000/svg"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   aria-hidden="true"
   focusable="false"
   width="1.13em"
   height="1em"
   style="vertical-align: -0.125em;-ms-transform: rotate(360deg); -webkit-transform: rotate(360deg); transform: rotate(360deg);"
   preserveAspectRatio="xMidYMid meet"
   viewBox="0 0 576 512"
   class="iconify"
   data-icon="fa-solid:home"
>

   <path
       d="M280.37 148.26L96 300.11V464a16 16 0 0 0 16 16l112.06-.29a16 16 0 0 0 15.92-16V368a16 16 0 0 1 16-16h64a16 16 0 0 1 16 16v95.64a16 16 0 0 0 16 16.05L464 480a16 16 0 0 0 16-16V300L295.67 148.26a12.19 12.19 0 0 0-15.3 0zM571.6 251.47L488 182.56V44.05a12 12 0 0 0-12-12h-56a12 12 0 0 0-12 12v72.61L318.47 43a48 48 0 0 0-61 0L4.34 251.47a12 12 0 0 0-1.6 16.9l25.5 31A12 12 0 0 0 45.15 301l235.22-193.74a12.19 12.19 0 0 1 15.3 0L530.9 301a12 12 0 0 0 16.9-1.6l25.5-31a12 12 0 0 0-1.7-16.93z"
       fill="currentColor"
   >
</path>
</svg>

There are several attributes added to <svg>:

  • aria-hidden="true". This hides icon from screen readers.
  • focusable="false". This attribute fixes Internet Explorer bug. In Internet Explorer <svg> tags can have focus, this attribute makes it behave like other browsers.
  • style. There are two parts of style:
    • vertical-align. This moves icon a bit below the baseline, making it behave like text. To remove it add data-inline="false" to the placeholder element. See block rendering
    • transform. 360 degrees rotation seems redundant, but it does serve a purpose. In Firefox until 2020 as well as older versions of other browsers, there was a bug that caused blurry edges of SVG when SVG left edge is place on sub-pixel. Rotation trick was a workaround for that bug. In the latest versions of all modern browsers this bug has been fixed.

Also, fill of <path> was changed to "currentColor". This forces icon to use current text color for fill. For icons that use stroke, Iconify also changes stroke to "currentColor".

Optimization

Sometimes an icon might flicker during load. Usually it is caused by a slow internet connection or long page.

If your page is large or your server is slow or visitor's internet connection is slow, it might take a while for page to load.

If you have placed Iconify script in footer before </body>, it might take a while for browser to initialize Iconify, so your visitors will see empty places where icons are supposed to be.

How to fix that? Move Iconify script to header between <head> and </head>.

<!DOCTYPE html>
<html lang="en">
   <head>
       <meta charset="UTF-8" />
       <title>Your page title</title>
       <script src="https://code.iconify.design/1/1.0.7/iconify.min.js"></script>
       <!-- the rest of your header here -->
   </head>
   <body>
       <!-- page content here -->
   </body>
</html>