Iconify Icon

add-api-provider

title: 'Iconify Icon Web Component Function: addAPIProvider'

Web component function: addAPIProvider

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/functions/add-api-provider/intro

API providers

include icon-components/api-providers

Usage

include icon-components/functions/add-api-provider/props

Example

src: icon-components/icon/add-api-provider.ts

include icon-components/functions/add-api-provider/footer

add-collection

title: 'Iconify Icon Web Component Function: addCollection'
types:
  IconifyJSON: '../types/iconify-json.md'
  IconifyIcon: '../types/iconify-icon.md'
functions:
  addIcon: './add-icon.md'

Web component function: addCollection

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/functions/add-collection/intro

Usage

include icon-components/functions/add-collection/props

Examples

src: icon-components/common/add-collection.js
replacements:
  - search: '@iconify/react'
    replace: 'iconify-icon'

src: icon-components/common/add-collection2.js
replacements:
  - search: '@iconify/react'
    replace: 'iconify-icon'

include icon-components/functions/add-collection/notes

API provider

include icon-components/functions/add-collection/provider

Example:

src: icon-components/common/add-collection3.js
replacements:
  - search: '@iconify/react'
    replace: 'iconify-icon'

Code above adds only one icon:

In HTML this icon can be used like this:

<iconify-icon icon="@custom:md:test"></iconify-icon>

include icon-components/functions/add-collection/custom

One icon

include icon-components/functions/add-collection/footer

add-icon

title: 'Iconify Icon Web Component Function: addIcon'
types:
  IconifyJSON: '../types/iconify-json.md'
  IconifyIcon: '../types/iconify-icon.md'
functions:
  addCollection: './add-collection.md'

Web component function: addIcon

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/functions/add-icon/intro

Usage

include icon-components/functions/add-icon/props

Examples

src: icon-components/common/add-icon.js
replacements:
  - search: '@iconify/react'
    replace: 'iconify-icon'

include icon-components/functions/add-icon/notes

API provider

include icon-components/functions/add-icon/provider

Example:

src: icon-components/common/add-icon2.js
replacements:
  - search: '@iconify/react'
    replace: 'iconify-icon'

Code above adds the following icon:

In HTML this icon can be used like this:

<iconify-icon icon="@custom:md:test"></iconify-icon>

include icon-components/functions/add-icon/custom

One icon

include icon-components/functions/add-icon/footer

build-icon

title: "Iconify Icon Web Component Function: buildIcon"
types:
  IconifyIcon: "../types/iconify-icon.md"
functions:
  getIcon: "./get-icon.md"
  loadIcon: "./load-icon.md"
  iconExists: "./icon-exists.md"
  iconLoaded: "./icon-exists.md"

Web component function: buildIcon

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/functions/build-icon/intro-component

Usage

include icon-components/functions/build-icon/usage

Result

include icon-components/functions/build-icon/result

Customizations

Second parameter is optional icon customizations. Available customizations:

include icon-components/customisations

For more details about dimensions see icon dimensions documentation.

For more details about transformations see icon transformations documentation.

Example

src: icon-components/common/build-icon.js
replacements:
  - search: "@iconify/svelte"
    replace: "iconify-icon"
extra:
  - src: icon-components/common/build-icon.json
    title: "Result:"

color

title: Changing Icon Color in Iconify Icon Web Component

Icon color

This tutorial is part of Iconify Icon web component tutorial.

include: icon-components/components/color-intro

src: icon-components/icon/color.html
css: components/color.scss
demo: true
class: components-color

include: icon-components/components/color-intro2

RGBA and HSLA colors {#opacity}

include icon-components/color-rgba

custom-loaders

title: "Iconify Icon Web Component Functions: setCustomIconLoader and setCustomIconsLoader"
types:
  IconifyJSON: "../types/iconify-json.md"
  IconifyIcon: "../types/iconify-icon.md"
functions:
  loadIcon: "./load-icon.md"

Custom icon loaders

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/functions/set-loaders/intro

Usage

include icon-components/functions/set-loaders/props

Example

src: icon-components/common/set-loader.js
replacements:
  - search: "@iconify/react"
    replace: "iconify-icon"

Make sure loader is set before any icons are rendered, otherwise component might attempt to load icon from API and fail to render it.

dimensions

title: Changing Icon Dimensions in Iconify Icon Web Component

Icon dimensions

This tutorial is part of Iconify Icon web component tutorial.

include: icon-components/components/size-intro

src: icon-components/icon/size-icon.html
css: icon/size.scss
demo: true
class: icon-size

If you want to control icon size with [prop]width and [prop]height in CSS, see how to remove icon dimensions section below.

Units

Both [prop]width and [prop]height can be used as properties and attributes.

Examples of [num]24px icon:

<iconify-icon icon="mdi:home" height="24"></iconify-icon>
<iconify-icon icon="mdi:home" height="24px"></iconify-icon>
<iconify-icon
	icon="mdi:home"
	style="font-size: 16px;"
	height="1.5em"
></iconify-icon>

Keyword "auto" {#auto}

include: icon-components/components/size-auto

<iconify-icon icon="mdi:home" height="auto"></iconify-icon>

Keywords "none" and "unset" {#unset}

include: icon-components/components/size-unset

src: icon-components/icon/size-unset.html
demo: true
class: 'icon-size icon-size--unset'

include: icon-components/components/size-unset-footer

Setting only width or height

In an example above, all icons only use [prop]height.

include icon-components/size-one

Example

include icon-components/size-example

Alignment

include icon-components/align-header

src: icon-components/icon/alignment.html
demo: true
demoHint: Using box-shadow to show icon dimensions
class: highlight-box

include icon-components/align-behavior

You can control alignment with [attr]preserveAspectRatio attribute. Default value is [str]xMidYMid slice.

Slice

Instead of adding space around icon to fit it in bounding box, browser can also cut parts of icon that do not fit.

To cut parts of icon, add [attr]preserveAspectRatio="xMidYMid slice" to icon:

src: icon-components/icon/alignment-slice.html
demo: true
demoHint: Using box-shadow to show icon dimensions
class: highlight-box

Horizontal alignment {#horizontal}

When...

...you can align icon horizontally.

To align icon horizontally, change [str]xMid in [attr]preserveAspectRatio to [str]xMin or [str]xMax:

Examples of aligning wide icon:

src: icon-components/icon/alignment-horizontal.html
demo: true
demoHint: Using box-shadow to show icon dimensions
class: highlight-box

Examples of aligning tall icon with slice enabled:

src: icon-components/icon/alignment-horizontal-slice.html
demo: true
demoHint: Using box-shadow to show icon dimensions
class: highlight-box

Vertical alignment {#vertical}

When...

...you can align icon vertically.

To align icon vertically, change [str]YMid in [attr]preserveAspectRatio to [str]YMin or [str]YMax:

Examples of aligning tall icon:

src: icon-components/icon/alignment-vertical.html
demo: true
demoHint: Using box-shadow to show icon dimensions
class: highlight-box

Examples of aligning wide icon with slice enabled:

src: icon-components/icon/alignment-vertical-slice.html
demo: true
demoHint: Using box-shadow to show icon dimensions
class: highlight-box

Vertical and horizontal alignment {#full-alignment}

You can add both horizontal and vertical alignment to icon.

One of alignments will have no effect. For example, if icon is too tall, horizontal alignment is ignored because icon is already aligned to both left and right sides.

src: icon-components/icon/alignment-both.html
demo: true
demoHint: Using box-shadow to show icon dimensions
class: highlight-box

disable-cache

title: "Iconify Icon Web Component Function: disableCache"
functions:
  enableCache: "./enable-cache.md"
  addIcon: "./add-icon.md"
  addCollection: "./add-collection.md"

Web component function: disableCache

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/functions/cache/deprecated

include icon-components/functions/cache/intro-disable

Usage

include icon-components/functions/cache/props

Storage types

include icon-components/functions/cache/storage-types

Examples

src: icon-components/common/disable-cache.js
replacements:
  - search: "@iconify/react"
    replace: "iconify-icon"

Another example:

src: icon-components/common/disable-cache2.js
replacements:
  - search: "@iconify/react"
    replace: "iconify-icon"

Notes

include icon-components/functions/cache/notes

enable-cache

title: "Iconify Icon Web Component Function: enableCache"
functions:
  disableCache: "./disable-cache.md"
  addIcon: "./add-icon.md"
  addCollection: "./add-collection.md"

Web component function: enableCache

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/functions/cache/deprecated

include icon-components/functions/cache/intro-enable

Usage

include icon-components/functions/cache/props

Storage types

include icon-components/functions/cache/storage-types

Example

src: icon-components/common/enable-cache.js
replacements:
  - search: "@iconify/react"
    replace: "iconify-icon"

Notes

include icon-components/functions/cache/notes

get-icon

title: 'Iconify Icon Web Component Function: getIcon'
types:
  IconifyIcon: '/docs/types/iconify-icon.md'

Web component function: getIcon

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/functions/get-icon/intro

Usage

include icon-components/functions/get-icon/props

Examples

src: icon-components/common/get-icon.js
extra:
  - src: icon-components/iconify/get-icon.json
    title: 'Result:'
replacements:
  - search: '@iconify/react'
    replace: 'iconify-icon'

Another example:

src: icon-components/common/get-icon2.js
extra:
  - src: icon-components/iconify/get-icon2.json
    title: 'Result:'
replacements:
  - search: '@iconify/react'
    replace: 'iconify-icon'

Example with bad icon name, returns null:

src: icon-components/common/get-icon-null.js
replacements:
  - search: '@iconify/react'
    replace: 'iconify-icon'

icon-exists

title: "Iconify Icon Web Component Function: iconLoaded"

Web component function: iconLoaded

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/functions/icon-loaded/intro

Usage

include icon-components/functions/icon-loaded/props

Example

import { iconLoaded, loadIcons } from "iconify-icon";

function renderLeftArrow() {
  // Check if 'bi:arrow-left' is available
  if (iconLoaded("bi:arrow-left")) {
    // Return HTML for 'bi:arrow-left'
    return '<iconify-icon icon="bi:arrow-left"></iconify-icon>';
  }

  // Load icon. Bad example because this should use a callback to re-render arrow in a stateful
  // component, but this code example is about iconLoaded(), not loadIcons()

  // Function loadIcons() is asynchronous, so in this example it will only trigger loading, but
  // icon data will not be available immediately
  loadIcons(["bi:arrow-left"]);

  // Return '<'
  return "<span>&lt;</span>";
}

Legacy

include icon-components/functions/icon-loaded/legacy

icon-name

title: 'Iconify Type: IconifyIconName'

IconifyIconName type

include types/iconify-icon-name

API providers

include icon-components/api-providers-short

Examples

src: icon-components/iconify/icon-name.json
title: 'md:home'
hint: Because prefix does not contain hyphen, icon can also be referred as 'md-home'

Another example:

src: icon-components/iconify/icon-name2.json
title: '@local:line-icons:arrow-left'

icon

title: Icon Attribute in Iconify Icon Web Component
navigation: './index.md'
functions:
  addIcon: './add-icon.md'

Icon attribute

This tutorial is part of Iconify Icon web component tutorial.

When using Iconify icon components, you can pass icon data to component instead of icon name, like this:

import { Icon } from '@iconify/react';
import arrowLeft from '@iconify-icons/bi/arrow-left';

function renderLeftArrow() {
	return <Icon icon={arrowLeft} />;
}

Unfortunately, the same syntax is not available for the web component. Attributes in HTML elements cannot be complex objects, making it harder to pass icon data to a web component.

How to solve this?

Assigning icon name

Best and easiest solution is to assign icon name to icon using [func]addIcon() function:

import { addIcon } from 'iconify-icon';
import arrowLeft from '@iconify-icons/bi/arrow-left';

addIcon('arrow-left', arrowLeft);

function renderLeftArrow() {
	return '<iconify-icon icon="arrow-left"></iconify-icon>';
}

Serialising data

Web component also supports serialised objects for [prop]icon attribute:

import arrowLeft from '@iconify-icons/bi/arrow-left';

function renderLeftArrow() {
	const node = document.createElement('iconify-icon');
	node.setAttribute('icon', JSON.stringify(arrowLeft));
	return node.outerHTML;
}

Or this if you need to render HTML:

import arrowLeft from '@iconify-icons/bi/arrow-left';

const replacements = {
	'&': '&amp;',
	'<': '&lt;',
	'>': '&gt;',
	'"': '&quot;',
	"'": '&#039;',
};

function stringify(data) {
	return JSON.stringify(arrowLeft).replace(
		/[&<>"']/g,
		(char) => replacements[char]
	);
}

const arrowLeftString = JSON.stringify(arrowLeft);

function renderLeftArrow() {
	return '<iconify-icon icon="' + arrowLeftString + '"></iconify-icon>';
}

Using property

Instead of setting attribute, you can also set property, which accepts objects:

import arrowLeft from '@iconify-icons/bi/arrow-left';

function renderLeftArrow() {
	const node = document.createElement('iconify-icon');
	node.icon = arrowLeft;
	return node.outerHTML;
}

index

title: Iconify Icon Web Component
replacements:
  - code: "60k"
    value: "${counters.icons-short}"
  - code: "0.0.4"
    value: "${iconify-icon.version}"
types:
  IconifyIcon: "../types/iconify-icon.md"
functions:
  addCollection: "./add-collection.md"
  addIcon: "./add-icon.md"
  iconExists: "./icon-exists.md"
  iconLoaded: "./icon-exists.md"
  listIcons: "./list-icons.md"
  loadIcons: "./load-icons.md"
  loadIcon: "./load-icon.md"
  getIcon: "./get-icon.md"
  enableCache: "./enable-cache.md"
  disableCache: "./disable-cache.md"
  addAPIProvider: "./add-api-provider.md"
  buildIcon: "./build-icon.md"
  setFetch: "./set-fetch.md"
  setCustomIconLoader: "./custom-loaders.md"
  setCustomIconsLoader: "./custom-loaders.md"

Iconify Icon web component

Iconify Icon is a web component renders icons.

Usage

It is designed to be as easy to use as possible.

src: icon-components/icon/usage.html
demo: true
demoFirst: false
class: sample-big

Supported frameworks

Web component can be used in HTML without any UI framework. See usage examples below.

It also works great with all modern frameworks that support web components:

However, some UI frameworks require custom wrappers:

Layout shift

Web component is not rendered instantly. There could be a few milliseconds delay.

This is caused by:

This might cause layout shift.

To avoid layout shift, add this to your CSS:

iconify-icon {
  display: inline-block;
  width: 1em;
  height: 1em;
}

Icon data on demand

Instead of embedding an entire icon, all you need to do is provide an icon name in [prop]icon attribute.

Web component will retrieve icon data from Iconify API, then will render SVG in shadow DOM.

There are over 60k icons available from many open source icon sets.

Don't want to rely on third party API servers? You can host your own Iconify API. You can also use it with your own icons.

Shadow DOM

SVG is rendered in shadow DOM. What does that mean?

Sometimes this can be a disadvantage, for example, if you do want to access icon content to perform CSS or JavaScript based animations. If you do not want a web component that uses shadow DOM, take a look at Iconify icon components.

SSR hydration {#ssr}

One of the issues a web component solves is a hydration, which is used by many modern UI frameworks.

Server side rendering is becoming more and more popular, hydration is complex and can easily be broken by a mismatched DOM.

What is hydration? Hydration is a process of matching content generated on server and content generated by UI framework in browser. Instead of re-rendering document, a UI framework uses HTML generated on server. This is the basic explanation. It is actually more complex than that, see various articles on SSR hydration.

There are several issues with hydrating icons:

Shadow DOM used by web components solves hydration problems. When a UI framework renders icon on server, it only renders [tag]iconify-icon element. During hydration process, UI framework only checks [tag]iconify-icon element, but not actual icon. This means:

Using shadow DOM to render icon leads to better experience for developers. No need to configure anything, no need to worry about icon data, no need to worry about conflicts. It just works.

Rendering only visible icons

As of version 2.0.0 of the web component, icons are rendered only when visible to the visitor.

For long documents with many icons, this improves the performance of pages by a lot.

As of version 2.1.0, you can opt out of this behavior by adding [html]noobserver attribute to web component's HTML:

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

Why not use icon font? {#icon-font}

Shadow DOM used by web component has big advantages over usual SVGs or framework specific components, but what about icon fonts?

Do not use icon fonts!!!

Icon fonts do not belong in modern web. They were a great solution when Internet Explorer was popular, web components did not exist and SVG support was buggy. Those bad times are over.

Registering the web component

For the web component to work, it needs to be registered. [npm]iconify-icon package does that automatically. All you need to do is include it on a page.

If you are building a project with a bundler, you can include the script by installing [npm]iconify-icon as a dependency and importing it in your project:

import "iconify-icon";

If you are not using bundles or want icon web component to be imported separately, add script to your document:

<script src="https://code.iconify.design/iconify-icon/0.0.4/iconify-icon.min.js"></script>

or

<script src="https://cdn.jsdelivr.net/npm/iconify-icon@0.0.4/dist/iconify-icon.min.js"></script>

Nuxt

When using component with Nuxt, you need to tell it that [tag]iconify-icon is a web component.

Example of [file]nuxt.config.ts:

import { defineNuxtConfig } from "nuxt3";

export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag) => tag === "iconify-icon",
    },
  },
});

Attributes

There are several attributes to customise icon appearance.

To change color (color can be changed only for monotone icons) or size, use style:

src: icon-components/icon/color-size.html
demo: true
class: sample-big

You can also change size using [attr]width and/or [attr]height attributes:

src: icon-components/icon/size.html
demo: true

If only one size attribute is set, another attribute is calculated using icon's width/height ratio.

You can also transform icon. Unlike CSS transformations, these transformations are done inside icon, which also affects icon's [prop]viewBox:

src: icon-components/icon/transform.html
demo: true

Attributes list

All attributes are also available as properties, so you can access them easy in JavaScript when working with elements.

Required attribute:

Optional attributes:

Functions

For advanced developers, web component offers several functions to control it.

These functions can be used to load custom icons, get icon data, preload icons from API, configure custom API and so on. See functions list below.

Functions can be imported from:

First method is the most reliable because it is a simple import. It is used in all examples:

import { loadIcon } from "iconify-icon";

const name = "mdi:home";
loadIcon(name)
  .then((data) => {
    console.log("Loaded data for", name);
  })
  .catch(console.error);

For second method, class can be retrieved from custom elements' registry:

const IconifyIcon = window.customElements.get("iconify-icon");

const name = "mdi:home";
IconifyIcon.loadIcon(name)
  .then((data) => {
    console.log("Loaded data for", name);
  })
  .catch(console.error);

Third method can be used after creating a new icon element or accessing an existing element:

const IconifyIcon = document.createElement("iconify-icon");

const name = "mdi:home";
IconifyIcon.loadIcon(name)
  .then((data) => {
    console.log("Loaded data for", name);
  })
  .catch(console.error);

Functions are split in several groups (click function name to see more details and examples):

Instance functions {#instance}

These functions are available only on web component nodes:

Check available icons {#getting-icons}

include: icon-components/components/functions-list/getting-icons

Adding icons {#adding-icons}

include: icon-components/components/functions-list/adding-icons

Custom loaders {#custom-loaders}

include: icon-components/components/functions-list/custom-loaders

Helper functions {#helper}

API functions {#api}

include: icon-components/components/functions-list/api

Internal API functions {#internal}

include: icon-components/components/functions-list/internal

inline

title: Vertical Alignment in Iconify Icon Web Component

Vertical alignment

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/vertical-align-intro

Inline attribute

include icon-components/components/inline-basic

src: icon-components/icon/inline.html
demo: true
class: iconify-inline-block

include icon-components/vertical-align-footer

list-icons

title: 'Iconify Icon Web Component Function: listIcons'

Web component function: listIcons

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/functions/list-icons/intro

Usage

include icon-components/functions/list-icons/props

Examples

src: icon-components/common/list-icons.js
replacements:
  - search: '@iconify/react'
    replace: 'iconify-icon'

Another example:

src: icon-components/common/list-icons2.js
replacements:
  - search: '@iconify/react'
    replace: 'iconify-icon'

load-icon

title: 'Iconify Icon Web Component Function: loadIcon'
types:
  IconifyIconName: './icon-name.md'
  FullIconifyIcon: '/docs/libraries/utils/full-iconify-icon.md'
functions:
  loadIcons: './load-icons.md'

Web component function: loadIcon

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/functions/load-icon/intro

Usage

include icon-components/functions/load-icon/props

IconifyIconName type

include types/iconify-icon-name

Examples

Using [type]Promise syntax:

src: icon-components/common/load-icon.js
replacements:
  - search: '@iconify/react'
    replace: 'iconify-icon'

Async/await syntax:

src: icon-components/common/load-icon-async.js
replacements:
  - search: '@iconify/react'
    replace: 'iconify-icon'

If you want to load multiple icons, see [func]loadIcons().

load-icons

title: 'Iconify Icon Web Component Function: loadIcons'
functions:
  getIcon: './get-icon.md'
  loadIcon: './load-icon.md'
types:
  IconifyIconName: './icon-name.md'

Web component function: loadIcons

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/functions/load-icons/intro

Usage

include icon-components/functions/load-icons/props

Icons list

include icon-components/functions/load-icons/props-icons

Callback

include icon-components/functions/load-icons/props-callback

IconifyIconName type

include types/iconify-icon-name

Examples

Simple callback that loads one icon:

src: icon-components/common/load-icons.js
replacements:
  - search: '@iconify/react'
    replace: 'iconify-icon'

Async version of [func]loadIcons():

src: icon-components/common/load-icons-async.js
replacements:
  - search: '@iconify/react'
    replace: 'iconify-icon'

If you want to load only one icon, there is also [func]loadIcon() that is easier to use.

modes

title: Rendering Modes in Iconify Icon Web Component

Rendering modes

This tutorial is part of Iconify Icon web component tutorial.

Web component supports several icon rendering modes.

Modes

There are 4 modes supported by web component:

Demo showing 2 icons (one monotone, one with palette) rendered with 4 modes:

include icon-components/modes-demo

Code samples

What do these modes actually look like in DOM?

Examples for [icon]mdi:home (used in modes demo above) icon:

hint: 'svg mode'
src: icon-components/common/modes-svg.html
extra:
  - src: icon-components/common/modes-bg.html
    hint: 'bg mode'
  - src: icon-components/common/modes-mask.html
    hint: 'mask mode'

Why not just render SVG? {#why}

You are probably wondering, why is it even needed? Isn't [tag]svg enough?

Rendering icon as [tag]svg works for most icons, but it does not always work for icons that use SVG animations.

SVG animations cannot start until document is ready. It might seem like a small thing, but animations not rendering quickly enough can cause bad user experience. This issue can be caused by small things, such as statistics script failing to load or ad code loading slowly. If at least one server that page is loading resources from is unreachable, it might break all animated SVGs on page. Async and defer attributes do not help. Issue can even be caused by script in an iframe.

Animation delay demo {#delay-demo}

Below is an [tag]iframe that shows icon rendering issue. It contains animated icon, rendered as [tag]svg and as background image. Both icons render instantly, but animation in [tag]svg does not start for few seconds because document is still loading.

include icon-components/frames/delay-demo-1up

To make things worse, this demo, which is in [tag]iframe, affects the main document. Logo on this page is rendered as [tag]svg and it contains animations. Refresh this page to see how slow script in a frame prevents SVG animations in unrelated icons in the main document.

Backgrounds and masks

Background images cannot use [prop]currentColor, but they do keep icon's palette, so icons with palette can be rendered as background image.

But what to do if icon uses [prop]currentColor? Solution is to use icon as mask and set background color to [prop]currentColor.

Combination of background and mask images make it possible to use almost all SVGs as URLs. The only icons that cannot be rendered correctly are icons that mix [prop]currentColor and hardcoded palette.

See Icons in Pure CSS article by Anthony Fu that explains it in more details.

SVG animations

When icon has animations, animations start immediately if it is rendered as mask or background, solving animation delay issue mentioned few sections above.

However, there is another issue: browser cache in Chrome. Image is rendered as URL. If URL is already in browser cache, Chrome does not restart animation. That means consequent renders of the same animated icons can bug out.

include icon-components/frames/delay-demo-freeze-1up

So there are issues with SVG animations when used as background or mask too. Web component solves it by adding random commented out content to icon, which causes it to bypass browser cache.

include icon-components/frames/delay-demo-icon-1up

Which mode to use? {#choices}

Web component will automatically use the best mode:

react

title: 'Iconify Icon Web Component with React'

Iconify Icon web component with React

This tutorial is part of Iconify Icon web component tutorial.

Iconify icon web component works well with React, but there are few problems:

Iconify Icon for React

These problems are solved by Iconify Icon for React.

It is a wrapper for web component that provides support for [prop]className, allows to use objects with [prop]icon and provides typings for React component.

Installation

Instead of [npm]iconify-icon package, install [npm]@iconify-icon/react package:

npm install --save-dev @iconify-icon/react

yarn add --dev @iconify-icon/react

Usage

Import [prop]Icon component from [npm]@iconify-icon/react, set icon in [prop]icon property:

import React from 'react';
import { Icon } from '@iconify-icon/react';

export function Alert() {
	return (
		<div className="alert">
			<Icon icon="mdi-light:alert" />
			Important notice with alert icon!
		</div>
	);
}

Usage with objects

You can pass objects in [prop]icon property:

import React from 'react';
import { Icon } from '@iconify-icon/react';
import alertIcon from '@iconify-icons/mdi-light/alert';

export function Alert() {
	return (
		<div className="alert">
			<Icon icon={alertIcon} />
			Important notice with alert icon!
		</div>
	);
}

Functions

All other functions, listed in Iconify Icon web component tutorial, are available. You can import them directly from [npm]@iconify-icon/react package:

import React from 'react';
import { Icon, addIcon } from '@iconify-icon/react';

addIcon('alert', {
	body: '<path fill="currentColor" d="M1 21L11.5 2.813L22 21H1Zm19.268-1L11.5 4.813L2.732 20h17.536ZM11 14v-4h1v4h-1Zm0 2h1v2h-1v-2Z"/>',
	width: 24,
	height: 24,
});

export function Alert() {
	return (
		<div className="alert">
			<Icon icon="alert" />
			Important notice with alert icon!
		</div>
	);
}

See Iconify Icon web component for list of all attributes, functions and usage examples. [npm]@iconify-icon/react is only a wrapper for [npm]iconify-icon, not a different component, it supports all the same properties and functions.

set-fetch

title: 'Iconify Icon Web Component Function: setFetch'

Web component function: setFetch

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/functions/set-fetch/intro-component

Why is it needed? {#why}

include: icon-components/functions/set-fetch/why

include: icon-components/functions/set-fetch/nodejs

Usage

include: icon-components/functions/set-fetch/usage

Steps

include: icon-components/functions/set-fetch/component
replacements:
  - search: '@iconify/svelte'
    replace: 'iconify-icon'

include: icon-components/functions/set-fetch/bundle

solid

title: 'Iconify Icon Web Component with SolidJS'

Iconify Icon web component with SolidJS

This tutorial is part of Iconify Icon web component tutorial.

Currently, SolidJS has poor support for web components. It is caused by issues in the web components spec. When setting a property to a web component, it sometimes does not work as expected.

Workaround

Workaround for Solid usage is to force Solid to use attributes instead of properties:

<iconify-icon attr:icon="mdi-light:home"></iconify-icon>

Iconify Icon for Solid

Iconify Icon for Solid solves that by mapping properties to attributes in a native Solid component, so you can use the web component without any issues.

It also provides typings for the component, making it easier to use in JSX and supports objects for [prop]icon property.

Installation

Instead of [npm]iconify-icon package, install [npm]@iconify-icon/solid package:

npm install --save-dev @iconify-icon/solid

yarn add --dev @iconify-icon/solid

Usage

Import [prop]Icon component from [npm]@iconify-icon/solid, set icon in [prop]icon property:

import { Icon } from '@iconify-icon/solid';

export default () => {
	return (
		<div class="alert">
			<Icon icon="mdi-light:alert" />
			Important notice with alert icon!
		</div>
	);
};

Usage with objects

You can pass objects in [prop]icon property:

import { Icon } from '@iconify-icon/solid';
import alertIcon from '@iconify-icons/mdi-light/alert';

export default () => {
	return (
		<div class="alert">
			<Icon icon={alertIcon} />
			Important notice with alert icon!
		</div>
	);
};

Functions

All other functions, listed in Iconify Icon web component tutorial, are available. You can import them directly from [npm]@iconify-icon/solid package:

import { Icon, addIcon } from '@iconify-icon/solid';

addIcon('alert', {
	body: '<path fill="currentColor" d="M1 21L11.5 2.813L22 21H1Zm19.268-1L11.5 4.813L2.732 20h17.536ZM11 14v-4h1v4h-1Zm0 2h1v2h-1v-2Z"/>',
	width: 24,
	height: 24,
});

export default () => {
	return (
		<div class="alert">
			<Icon icon="alert" />
			Important notice with alert icon!
		</div>
	);
};

See Iconify Icon web component for the list of all attributes, all functions and usage examples. [npm]@iconify-icon/solid is only a wrapper for [npm]iconify-icon, not a different component, it supports all the same properties and functions.

transform

title: Transforming Icon in Iconify Icon Web Component

Transformations

This tutorial is part of Iconify Icon web component tutorial.

include icon-components/transform-intro

CSS vs Iconify transformations {#css}

include icon-components/transform-compare

Example:

src: icon-components/icon/rotate-comparison.html
demo: true
demoHint: Using box-shadow to show icon dimensions
class: highlight-box

include icon-components/transform-compare-footer

Flip

include icon-components/components/transform-flip

src: icon-components/icon/flip.html
hint: Using "flip" attribute
demo: true

Rotation

include icon-components/components/transform-rotate

src: icon-components/icon/rotate.html
demo: true

Rotate and flip

include icon-components/components/transform-footer