Iconify for React with API

In addition to SVG framework, Iconify offers native components for several popular UI frameworks. Iconify for React is one of such components.

Yet another icon component? What are advantages over other icon components?

  • One syntax for over 70,000 icons from 80+ icon sets.
  • Renders SVG. Many components simply render icon fonts, which look ugly. Iconify renders pixel perfect SVG.
  • Loads icons on demand. No need to bundle icons, component will automatically load icon data for icons that you use from Iconify API.

Component variations

There are two variations of Iconify for React:

What is the difference?

Iconify for React

Iconify for React is a basic component. It works offline and does not have any dependencies. Icon data is provided as parameter to component.

import { Icon } from '@iconify/react';
import home from '@iconify-icons/mdi-light/home';
<Icon icon={home} />

Iconify for React with API

Iconify for React with API is a more advanced component. It works similar to SVG framework. You do not need to provide icon data, you can reference icon by name and component will automatically retrieve icon data from Iconify API.

import { Icon } from '@iconify/react-with-api';
<Icon icon="mdi-light:home" />

Downside of such component is it requires internet access to retrieve icon data. You can provide icon data using icon bundles to allow it to work offline.

Installation

This documentation is for advanced component. Click here for documentation for basic component.

If you are using NPM:

npm install --save-dev @iconify/react-with-api

If you are using Yarn:

yarn add --dev @iconify/react-with-api

Usage

Install @iconify/react-with-api and import Icon component from it:

import { Icon } from '@iconify/react-with-api';

Then use Icon component with icon name as icon parameter:

<Icon icon="mdi-light:home" />

Component will automatically retrieve data for mdi-light:home from Iconify API and render it. There are over 70,000 icons available on Iconify API from various free and open source icon sets, including all the most popular icon sets.

Offline use

Retrieving icon data from Iconify API requires visitor to be online. What if you want to use component offline or on local network?

There are several options:

See icon bundles for Iconify for React documentation.

Properties

You can pass any custom properties to Icon.

Required properties:

Optional properties:

  • inline, boolean toggles inline or block mode.
  • width, string | number icon width.
  • height, string | number icon height.
  • hFlip, boolean flips icon horizontally.
  • vFlip, boolean flips icon vertically.
  • flip, string alternative to hFlip and vFlip.
  • rotate, number | string rotates icon.
  • color, string changes icon color.
  • hAlign horizontally aligns content inside icon.
  • vAlign vertically aligns content inside icon.
  • slice alignment behaviour: "meet" or "slice".
  • align, string aligns content inside icon, alternative to hAlign, vAlign and slice.

See below for more information on each optional property.

In addition to the properties mentioned above, the icon component accepts any other properties and events. All other properties and events will be passed to generated SVG element, so you can do stuff like assigning onClick event, setting the inline style, add title and so on.

Icon

Icon name syntax is icon="prefix:icon-name" or icon="prefix-icon-name". Second syntax can be used if prefix does not contain "-", it is kept for compatibility with icon fonts.

For example, icon="fa-arrow-left" and icon="fa:arrow-left" are identical (both have a prefix "fa"), but icon="flat-color-icons:voice-presentation" and 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).

There are over 70,000 icons available from 80+ icon sets. Browse icons sets to see all available icons.

Inline icon

There are two components in Iconify for React: Icon and InlineIcon.

They are identical, except for one thing: InlineIcon adds vertical-align style to <svg>. This makes icon behave like an icon font.

See inline icons tutorial for details.

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 a monotone icon simply change text color.

<Icon icon="mdi:home" style={{ color: 'red' }} />

For various ways to set color, see how to change icon color in Iconify for React.

Dimensions and alignment

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.

There are several ways to change icon dimensions:

  • Setting font-size in style (or fontSize if you are using inline style).
  • Setting width and/or height property.

Values for width and height can be numbers or strings.

If you set only one dimension, another dimension will be calculated using the icon's width to height ratio. For example, if the icon size is 16 x 24, you set the height to 48, the width will be set to 32. Calculations work not only with numbers, but also with string values.

<Icon icon="mdi:home" style={{ fontSize: '24px' }} />

For various ways to change icon dimensions and alignment, see how to change icon dimensions in Iconify for React.

Transformations

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

These are not CSS transformations, transformations are applied inside SVG.

For more details see how to transform icon in Iconify for React.

Functions

This component offers functions, which developers can use to control icons.

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

Check available icons

There are several functions in this section:

Adding icons

Functions for adding icons to component:

Note: icons added to component with these functions are not stored in cache. Component caches only icons retrieved from API.

API functions

  • loadIcons(icons, callback?). Loads icons from API, calls optional callback when either all or part of icons have been loaded.
  • enableCache(). Enables caching in localStorage and sessionStorage.
  • disableCache(). Disables caching in localStorage and sessionStorage.
  • addAPIProvider(). Adds custom API provider. This is experimental function. API provider functionality is in development.

Internal functions

There are several internal functions that are exposed. They are intended to be used by implementations that want more control over component, such as Iconify Icon Finder. Use them carefully.

All internal functions are exposed as properties of internals object:

  • calculateSize(). Calculates icon size. It is used to calculate width if only height is set and vice versa.
  • getAPI(). Returns internal API module.
  • getAPIConfig(). Returns API configuration.
  • setAPIModule(provider). Sets API module for provider. This is experimental function intended for custom API providers. API provider functionality is in development.