Skip to content
On this page

Icons on demand

Iconify ecosystem has a unique feature: Iconify API.

It can be used to load icon data on demand and is used by Iconify icon components.

Skip to list of available components if you want to skip long explanation of how it all works.

How does it work?

Iconify icon components are very easy to use. All developer has to specify is an icon name:

html<iconify-icon icon="mdi:home"></iconify-icon>

Unlike regular icon components, Iconify icon components do not bundle icon data. They load only data for icons used on currently viewed page at run time.

<Icon icon="mdi:home" />
<iconify-icon icon="mdi:alert" />
Developer passes icon name as attribute for icon component.

API

Icon Names

Browser

Component requests data for icons from Iconify API.

API

Icon Data

Browser

API sends data for requested icons.

API hosts thousands of icons, but sends only data for icons that were requested.
<svg width="1em" height="1em" viewBox="0 0 24 24" ...>...</svg>
<iconify-icon icon="mdi:alert">#shadow-root<svg width="1em" height="1em" viewBox="0 0 24 24" ...>...</svg></iconify-icon>
Component renders SVG using data retrieved from Iconify API.

Advantages

Loading icon data on demand has its advantages and disadvantages over using regular icon components.

Advantages:

  • Very easy to use.
  • If you are using many icons on various pages, bundle size is smaller because icon data is loaded only as needed.
  • Can be used with customisable themes, where developer doesn't know which icons theme is using.
  • Small HTML. Icons are loaded only in browser, not server side rendered.

Disadvantages:

  • Requires access to Iconify API, making it unusable for offline applications. You can host your own API instance, but it is not trivial.
  • Icons might not render instantly. Even though there are multiple layers of caching icon data, there is a few milliseconds delay in rendering.

Components

There are several options:

Web component

Best option by far is web component. It is the most modern iteration, works with all UI frameworks and works great with server side rendering.

Usage is very simple:

html<iconify-icon icon="mdi:home"></iconify-icon>

See Iconify icon web component documentation.

Shadow DOM

Web component renders icon in Shadow DOM, separating it from main document.

That has its advantages and disadvantages over other components.

Advantages:

  • Separates icon from main DOM, so main DOM doesn't become bloated.
  • No conflicts with unique ids, which are used in some icons in masks, clip paths, animations and few other elements.
  • Works wonderfully with SSR, much better than UI framework native components: no ID conflicts, render is independent of framework rendering, so it doesn't cause any issues with hydration.

Disadvantages:

  • Accessing icon content, such as changing stroke-width, is not always possible. Depends on use case.
  • Cannot render icon without width and height, making it impossible to resize icon with those properties. Icon can be resized only with font-size.

If these disadvantages are unacceptable for your project, use "SVG framework" or one of UI framework specific components listed below.

SVG framework

SVG framework is an older iteration of web component. It was the first package developed in early stages of Iconify project.

Before end of 2020, web components were not usable because too many users were still using older browsers that do not support them, more specifically MS Edge and various old mobile browsers.

Usage is simple:

html<span class="iconify" data-icon="mdi:home"></span>

SVG framework finds all such elements in HTML and replaces them with <svg> elements.

This often causes problems with various UI frameworks, so SVG framework is not usable inside React/Vue/Svelte/etc... components.

See SVG framework documentation.

UI frameworks

Iconify offers components native to various UI frameworks:

Usage is as any other component:

jsx<Icon icon="mdi:home" />

These components behave differently than web component:

  • To avoid SSR errors, icons are rendered only after component is mounted. Otherwise, it breaks hydration.
  • Icons can be rendered without width and height attributes, making it easy to style in CSS.

Released under the Apache 2.0 License.