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.
• It can be used with customisable themes, where a 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

The best option by far is Web component. It is usable in HTML with or without UI frameworks.

Additionally, there are components for UI frameworks: React, Vue, Svelte, Ember.

In future, only iconify-icon web component will be supported. Why?

• SVG Framework is an old version of the web component, developed many years ago as an experiment when browser did not support web components. It has no place in modern development.
• Framework-specific components have issue with server side rendering. Web compponent solves those issues.

Web component

The 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 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 the 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.

UI frameworks

Iconify offers components native to various UI frameworks:

• React (warning: when using with Next.js, wrap it in a client-only component or switch to IconifyIcon web component!)
• Vue
• Svelte

Usage is as any other component:

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

These components behave differently than the web component:

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

You should consider using the iconify-icon web component instead of components mentioned above. Dynamic data loading does not work well with SSR. Web component solves those issues.

Legacy components

In addition to components listed above, there are several legacy components. They were created a long time ago, but no longer relevant in modern development.

These components are no longer updated, but can be used if you really need it:

• Vue 2 (Vue 3 was released a long time ago, no point in supporting the old version)
• Ember (Ember framework is outdated)
• SVG Framework (the oldest of components, has been replaced by the IconifyIcon web component)