Skip to content

Iconify for React

Iconify offers native icon components for several popular UI frameworks.

Iconify for React is one of such components.

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

  • One syntax for over 200,000 icons from 150+ icon sets.
  • Renders SVG. Many components simply render icon fonts, which look ugly. Iconify uses only 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.

Please be aware that this component is not designed for server side rendering. If you are using SSR, consider switching to Iconify Icon web component.

Installation

If you are using NPM:

npm install --save-dev @iconify/react

If you are using Yarn:

yarn add --dev @iconify/react

Usage

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

jsimport { Icon } from '@iconify/react';

Then use Icon component with icon name as icon parameter:

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

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

Availability of Iconify API is the biggest feature that makes Iconify components different from alternatives.

API sends data for icons on demand. Loading icons on demand has massive advantages over other methods:

  • There can be an unlimited number of icons, giving you more choices. Icons you do not use are not loaded.
  • No useless data. Icon sets usually have thousands of icons. Instead of bundling all icons, component retrieves only icons you use.

Next.js

Component is compatible with Next.js.

Component does not retrieve icon data until it is mounted. For server side rendering it means HTML will not include SVGs, they will be dynamically added only when hydrating DOM on client side.

If you do want to render SVGs on server side, provide icon data as parameter instead of icon name or use a different icon component.

API support in Next.js

If you want to use icon component's functions that load icon data from API in Next.js, you need Fetch API.

Older versions of Node.js do not support Fetch API. It is available in Node.js version 17 using flag "--experimental-fetch", but without it, Fetch API is not available. That means the icon component cannot retrieve icon data from Iconify API when used on a server side in Node.js environment.

How to support API in server side rendering?

  1. Install cross-fetch (if you are using CommonJS) or node-fetch (if you are using modules) as dependency.
  2. Use internal setFetch() function to set third party Fetch API before using any icon component functions.
jsimport { _api } from '@iconify/react';
import fetch from 'cross-fetch';
//  import fetch from 'node-fetch';

// Set Fetch API before doing anything
_api.setFetch(fetch);

This code must be added only to script that runs on the server side, not bundled for client side use. Browsers already support Fetch API, so this code is not needed in browsers.

Properties

You can pass any custom properties to Icon.

Required properties:

Optional properties:

  • inline, boolean changes vertical alignment.
  • 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.
  • onLoad, function is a callback that is called when icon data has been loaded. See below.

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 is a string, which has 3 parts:

@api-provider:icon-prefix:icon-name
provider prefix name
  • provider points to API source. Starts with "@", can be empty (empty value is used for public Iconify API).
  • prefix is name of icon set.
  • name is name of icon.

Examples of valid icon names:

  • flat-color-icons:voice-presentation - icon is "voice-presentation" from Flat Color Icons icon set, from public Iconify API.
  • mdi-light:home - icon is "home" from Material Design Light icon set, from public Iconify API.

Exceptions:

  • If the API provider is empty, it can be skipped (like in examples above).
  • If prefix does not contain "-", prefix and icon name can be separated with hyphen. This is to support people migrating from icon fonts. For example, fa:arrow-left and fa-arrow-left are identical because "fa" does not contain hyphen.

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

You can also add custom API providers for more icon choices. See API providers documentation.

Color

You can only change the 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.

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

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

Dimensions

By default, icon height is set to "1em", icon width is changed dynamically based on the icon's width/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/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.

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

For various ways to change icon dimensions, 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.

onLoad

onLoad property is an optional callback function. It is called when icon data has been loaded.

It is not an event, such as click event for links, it is a simple callback function.

When onLoad is called:

  • If value of icon property is an object, onLoad is not called.
  • If value of icon property is a string and icon data is available, onLoad is called on first render.
  • If value of icon property is a string and icon data is not available, onLoad is called on first re-render after icon data is retrieved from API.

What is the purpose of onLoad? To let you know when Icon component renders an icon and when it does not render anything. This allows you to do things like adding class name for the parent element, such as "container--with-icon" that modify layout if icon is being displayed.

Functions

Component exports various 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 the component:

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

Helper functions

  • replaceIDs(html). Randomises IDs in generated string. This should be used when rendering icon based on data returned by getIcon() to make sure elements inside each icon have unique IDs.
  • calculateSize(). Calculates icon size. It is used to calculate width if only height is set and vice versa.
  • buildIcon(icon, customisations?). Generates data used by icon component. This can be used if you prefer to generate <svg> yourself. Data includes attributes for <svg> and inner HTML.

API functions

Internal API functions

There are several internal API functions that are exposed. They are intended to be used by developers that need more control over the component. For example, it is used in Sketch and Figma plug-ins. Use them carefully.

All internal API functions are exposed as properties of _api object:

  • getAPI(). Returns internal API module.
  • getAPIConfig(). Returns API configuration.
  • setAPIModule(provider). Sets API module for provider. This is an experimental function intended for custom API providers that use custom module for retrieving data from API.
  • setFetch(fetch). Set custom Fetch API.
  • getFetch(). Returns used fetch() function, null if Fetch API is not available.

Released under the Apache 2.0 License.