Iconify for React

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.

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 component
import { Icon } from '@iconify/react';

// Import icon data
// You can import icon with any name instead of 'home'
// because exports are not named
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';
<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 basic component. Click here for documentation for advanced component.

If you are using NPM:

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

If you are using Yarn:

yarn add --dev @iconify/react@beta

This package does not include icons. Icons are split into separate packages that available at NPM. See below.

Usage

Install @iconify/react@beta and packages for selected icon sets. Import Icon from @iconify/react and icon data for icon you want to use:

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

Then use Icon component with icon data as icon parameter:

<Icon icon={home} />

String syntax

Version 2 of component supports string syntax. String syntax passes icon name to the component.

With this method the icon needs to be added only once. That means if you have multiple components using home icon, you can add it only in your main component. This makes it easy to swap icons for an entire application.

import React from 'react';
import { Icon, addIcon } from '@iconify/react';
import homeIcon from '@iconify-icons/mdi-light/home';

addIcon('home', homeIcon);

export function MyComponent() {
   return (
       <div>
           <Icon icon="home" />
       </div>

   );
}

Instead of adding icons one by one using addIcon(), you can import an entire icon set using addCollection():

import React from 'react';
import { Icon, addCollection } from '@iconify/react';

// Import requires bundler that can import JSON files
import jamIcons from '@iconify/json/json/jam.json';

// Function automatically adds prefix from icon set, which in this case is 'jam', followed by ':', so
// icon names added by function should be called with prefix, such as 'jam:home'
addCollection(jamIcons);

// Example without prefix, all icons will have names as is, such as 'home'
// addCollection(jamIcons, false);

export function MyComponent() {
   return (
       <div>
           <Icon icon="jam:home" />
       </div>

   );
}

Example above imports an entire icon set.

To learn how to create smaller bundles, check out Iconify bundles documentation.

Properties

You can pass any custom properties to Icon.

Required properties:

  • icon, IconifyIcon | string icon data or name of icon registered with addIcon().

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

This is a basic component, it cannot retrieve icon data from Iconify API. That means you need to provide icon data yourself.

All icons available with Iconify components and Iconify SVG framework can be imported from NPM packages.

Each icon set has its own package that you need to install. Package names start with @iconify-icons/, followed by icon set prefix.

Each icon is stored in a separate file, so only icons you import are bundled. To import an icon, combine package name and icon name in import statement.

Examples:

  • mdi:login-variant from Material Design Icons can be imported from @iconify-icons/mdi/login-variant.
  • bi:chat-quote from Bootstrap Icons can be imported from @iconify-icons/bi/chat-quote.
  • tabler:info-circle from Tabler Icons can be imported from @iconify-icons/tabler/info-circle.

...and so on.

Variable name in import statement is irrelevant because all exports are default exports.

CommonJS icon modules

Icons in icon packages are ES modules.

Sometimes you might need CommonJS module, for example, when importing icon data in Node.js.

There are alternative icon packages that use CommonJS modules: @iconify/icons-*. Icons are identical, the only difference is export method. To swap from ES package to CommonJS package, use "@iconify/icons-" before icon set prefix in package name instead of "@iconify-icons/".

For example, Material Design Icons are available as @iconify-icons/mdi with ES exports, as @iconify/icons-mdi with CommonJS exports.

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={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={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.