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 80,000 icons from 90+ 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:
- Iconify for React.
- Iconify for React with API (this documentation).
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 from Iconify API and render it. There are over 80,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:
- You can create icon bundles for icons that you use.
- You can install local copy of Iconify API instead of relying on Iconify public API servers.
- You can also use icon components, similar to basic React component.
See icon bundles for Iconify for React documentation.
Properties
You can pass any custom properties to Icon.
Required properties:
- icon, IconifyIcon | string icon name or icon data.
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 80,000 icons available from 90+ 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:
- iconExists(name). Checks if an icon exists, returns boolean.
- listIcons(). Lists available icons, returns string[].
- getIcon(name). Returns icon data, returns IconifyIcon object.
Adding icons
Functions for adding icons to component:
- addIcon(). Adds one icon.
- addCollection(). Adds an icon set.
Note: icons added to component with these functions are not stored in cache. Component caches only icons retrieved from API.
Helper functions
- replaceIDs(html). Randomizes 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.
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 API functions
There are several internal API 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 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 experimental function intended for custom API providers. API provider functionality is in development.