# Iconify Icon

# add-api-provider

```yaml
title: 'Iconify Icon Web Component Function: addAPIProvider'
```

# Web component function: addAPIProvider

This tutorial is part of [Iconify Icon web component tutorial](./index.md#functions).

`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

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

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

# add-collection

```yaml
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](./index.md#functions).

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

## Usage

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

## Examples

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

```yaml
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:

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

Code above adds only one icon:

- `[prop]provider` is `[str]custom`.
- `[prop]prefix` is `[str]md`.
- `[prop]name` is `[str]test`.

In HTML this icon can be used like this:

```html
<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

```yaml
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](./index.md#functions).

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

## Usage

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

## Examples

```yaml
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:

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

Code above adds the following icon:

- `[prop]provider` is `[str]custom`.
- `[prop]prefix` is `[str]md`.
- `[prop]name` is `[str]test`.

In HTML this icon can be used like this:

```html
<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

```yaml
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](./index.md#functions).

`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](./dimensions.md).

For more details about transformations see [icon transformations documentation](./transform.md).

## Example

```yaml
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

```yaml
title: Changing Icon Color in Iconify Icon Web Component
```

# Icon color

This tutorial is part of [Iconify Icon web component tutorial](./index.md).

```yaml
include: icon-components/components/color-intro
```

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

```yaml
include: icon-components/components/color-intro2
```

## RGBA and HSLA colors {#opacity}

`include icon-components/color-rgba`

# custom-loaders

```yaml
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](./index.md#functions).

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

## Usage

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

## Example

```yaml
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

```yaml
title: Changing Icon Dimensions in Iconify Icon Web Component
```

# Icon dimensions

This tutorial is part of [Iconify Icon web component tutorial](./index.md).

```yaml
include: icon-components/components/size-intro
```

```yaml
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](#unset) section below.

## Units

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

Examples of `[num]24px` icon:

```html
<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}

```yaml
include: icon-components/components/size-auto
```

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

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

```yaml
include: icon-components/components/size-unset
```

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

```yaml
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`

```yaml
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:

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

### Horizontal alignment {#horizontal}

When...

- icon is too wide...
- icon is too tall and slice is enabled...

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

```yaml
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:

```yaml
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...

- icon is too tall...
- icon is too wide and slice is enabled...

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

```yaml
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:

```yaml
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.

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

# disable-cache

```yaml
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](./index.md#functions).

`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

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

Another example:

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

## Notes

`include icon-components/functions/cache/notes`

# enable-cache

```yaml
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](./index.md#functions).

`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

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

## Notes

`include icon-components/functions/cache/notes`

# get-icon

```yaml
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](./index.md#functions).

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

## Usage

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

## Examples

```yaml
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:

```yaml
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`:

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

# icon-exists

```yaml
title: "Iconify Icon Web Component Function: iconLoaded"
```

# Web component function: iconLoaded

This tutorial is part of [Iconify Icon web component tutorial](./index.md#functions).

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

## Usage

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

## Example

```js
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

```yaml
title: 'Iconify Type: IconifyIconName'
```

# IconifyIconName type

`include types/iconify-icon-name`

## API providers

`include icon-components/api-providers-short`

## Examples

```yaml
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:

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

# icon

```yaml
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](./index.md).

When using [Iconify icon components](../icon-components/index.md), you can pass icon data to component instead of icon name, like this:

```jsx
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:

```js
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:

```js
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:

```js
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:

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

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

# index

```yaml
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.

```yaml
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:

- Svelte and SvelteKit/Sapper.
- Vue 2 and Vue 3. Require changing config when used in Nuxt (see below).
- Lit.
- Ember.
- React and Next, but with small differences, such as using `[prop]class` instead of `[prop]className`. [Wrapper fixes it](./react.md).

However, some UI frameworks require custom wrappers:

- Solid. See [Iconify icon web component for Solid](./solid.md).

### Layout shift

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

This is caused by:

- JavaScript. Web component cannot be rendered until it is loaded and registered.
- Because of web component spec. Rendering is done asynchronously in browser, often causing tiny delay.

This might cause layout shift.

To avoid layout shift, add this to your CSS:

```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](../api/index.md), 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](/docs/api/hosting.md). You can also use it with your own icons.

## Shadow DOM

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

- HTML for icon is hidden, not part of the main document.
- It simplifies hydration when the web component is used in a UI framework with server side rendering. See below.
- Stylesheet used in the document does not affect icons, preventing potential conflicts.

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](../icon-components/index.md).

### 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:

- Icons might have unique IDs in elements, such as masks and clip paths. Using multiple icons on the same page requires using different IDs (or randomising them), which usually breaks hydration process.
- Dynamically loaded icon data cannot be rendered before hydration ends. This can be solved by rendering icon only after component has been mounted, but that might cause rendering delays and other issues.

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:

- Server side can generate only `[html]<iconify-icon icon="mdi:home"></iconify-icon>`, reducing document size.
- Web component can load icon data and render it immediately and independent of a UI framework, not waiting for a UI framework to mount the component.
- No issues with duplicate unique IDs. Each icon has its own document, so no need to change IDs of icon elements.
- Faster hydration. Icons can be complex, not checking icon content means less work for a UI framework.

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:

```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 are ugly. Browser renders icons using font rendering methods, which causes blurred icon edges and icons lose their sharpness.
- Icons rendered from icon fonts are often hard to align, resulting in misaligned icons.
- Browsers load huge fonts just to render few icons. This can be solved by using custom icon fonts, but doesn't solve other issues.
- No colored icons, only monotone. No SVG animations.

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:

```js
import "iconify-icon";
```

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

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

or

```html
<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`:

```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:

```yaml
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:

```yaml
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`:

```yaml
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:

- `[prop]icon`, `[type]IconifyIcon | string` icon name or icon data. Because attributes can only be strings, if you want to provide `[type]IconifyIcon` data, you need to either use property or `[js]JSON.stringify()` it. See [icon data](./icon.md).

Optional attributes:

- `[prop]mode`, `[type]string` sets icon rendering mode. See [rendering modes](./modes.md).
- `[prop]inline`, `[type]boolean` changes vertical alignment. See [vertical alignment](./inline.md).
- `[prop]width`, `[type]string | number` icon width. See [icon dimensions](./dimensions.md).
- `[prop]height`, `[type]string | number` icon height. See [icon dimensions](./dimensions.md).
- `[prop]flip`, `[type]string` flip icon. See [icon transformations](./transform.md).
- `[prop]rotate`, `[type]number | string` rotates icon. See [icon transformations](./transform.md).

## 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:

- `[npm]iconify-icon` package, which also bundles web component. Usable in browser and Node.js.
- Web component class as static methods, which is available after component is registered.
- `[tag]iconify-icon` node as methods, which are available after component is registered and new elements are created.

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

```js
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:

```js
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:

```js
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:

- `[func]restartAnimation()`. Restarts SVG animation, useful if you want to restart animation on hover event, as shown in right side navigation of this website.

### Check available icons {#getting-icons}

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

### Adding icons {#adding-icons}

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

### Custom loaders {#custom-loaders}

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

### Helper functions {#helper}

- `[func]calculateSize()`. Calculates icon size. It is used to calculate `[attr]width` if only `[attr]height` is set and vice versa.
- `[func]buildIcon(icon, customisations?)`. Generates data used by icon component. This can be used if you prefer to generate `[tag]svg` yourself. Data includes attributes for `[tag]svg` and inner HTML.

### API functions {#api}

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

### Internal API functions {#internal}

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

# inline

```yaml
title: Vertical Alignment in Iconify Icon Web Component
```

# Vertical alignment

This tutorial is part of [Iconify Icon web component tutorial](./index.md).

`include icon-components/vertical-align-intro`

## Inline attribute

`include icon-components/components/inline-basic`

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

`include icon-components/vertical-align-footer`

# list-icons

```yaml
title: 'Iconify Icon Web Component Function: listIcons'
```

# Web component function: listIcons

This tutorial is part of [Iconify Icon web component tutorial](./index.md#functions).

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

## Usage

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

## Examples

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

Another example:

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

# load-icon

```yaml
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](./index.md#functions).

`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:

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

Async/await syntax:

```yaml
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

```yaml
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](./index.md#functions).

`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:

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

Async version of `[func]loadIcons()`:

```yaml
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

```yaml
title: Rendering Modes in Iconify Icon Web Component
```

# Rendering modes

This tutorial is part of [Iconify Icon web component tutorial](./index.md).

Web component supports several icon rendering modes.

## Modes

There are 4 modes supported by web component:

- `[str]svg`: renders `[tag]svg` element.
- `[str]style`: uses either `[str]bg` or `[str]mask` mode, depending on icon palette.
- `[str]bg`: renders `[tag]span` element with icon as background image. Usable only for icons that have palette.
- `[str]mask`: renders `[tag]span` element with icon as mask image. Usable only for icons that do not have palette.

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:

```yaml
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](https://antfu.me/posts/icons-in-pure-css) 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:

- If icon has SVG animations, `[str]style` to render animations immediately.
- Otherwise `[str]svg`, which renders slightly faster in most browsers.

# react

```yaml
title: 'Iconify Icon Web Component with React'
```

# Iconify Icon web component with React

This tutorial is part of [Iconify Icon web component tutorial](./index.md).

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

- When using web components in React, you need to use `[prop]class` instead of `[prop]className` to pass class name.
- Property `[prop]icon` can only be a string.
- No JSX hints.

## 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:

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

```bash
yarn add --dev @iconify-icon/react
```

## Usage

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

```jsx
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:

```jsx
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](./index.md#functions), are available. You can import them directly from `[npm]@iconify-icon/react` package:

```jsx
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](./index.md) 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

```yaml
title: 'Iconify Icon Web Component Function: setFetch'
```

# Web component function: setFetch

This tutorial is part of [Iconify Icon web component tutorial](./index.md#functions).

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

## Why is it needed? {#why}

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

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

## Usage

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

## Steps

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

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

# solid

```yaml
title: 'Iconify Icon Web Component with SolidJS'
```

# Iconify Icon web component with SolidJS

This tutorial is part of [Iconify Icon web component tutorial](./index.md).

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:

```html
<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:

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

```bash
yarn add --dev @iconify-icon/solid
```

## Usage

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

```jsx
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:

```jsx
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](./index.md#functions), are available. You can import them directly from `[npm]@iconify-icon/solid` package:

```jsx
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](./index.md) 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

```yaml
title: Transforming Icon in Iconify Icon Web Component
```

# Transformations

This tutorial is part of [Iconify Icon web component tutorial](./index.md).

`include icon-components/transform-intro`

## CSS vs Iconify transformations {#css}

`include icon-components/transform-compare`

Example:

```yaml
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`

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

## Rotation

`include icon-components/components/transform-rotate`

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

## Rotate and flip

`include icon-components/components/transform-footer`