@iconify/react
Advanced tools
@iconify/react is a React component for Iconify, a versatile icon framework that allows you to use a wide range of icons from different icon sets. It provides a simple way to include icons in your React applications, supporting customizations such as size, color, and more.
Basic Icon Usage
This feature allows you to easily include an icon in your React component. You import the Icon component from @iconify/react and the specific icon from an icon set, then use it within your JSX.
import { Icon } from '@iconify/react';
import homeIcon from '@iconify-icons/mdi/home';
function App() {
return (
<div>
<Icon icon={homeIcon} />
</div>
);
}
export default App;Customizing Icon Size
This feature allows you to customize the size of the icon. You can set the width and height properties to adjust the icon's size.
import { Icon } from '@iconify/react';
import homeIcon from '@iconify-icons/mdi/home';
function App() {
return (
<div>
<Icon icon={homeIcon} width="48" height="48" />
</div>
);
}
export default App;Customizing Icon Color
This feature allows you to customize the color of the icon. You can set the color property to change the icon's color.
import { Icon } from '@iconify/react';
import homeIcon from '@iconify-icons/mdi/home';
function App() {
return (
<div>
<Icon icon={homeIcon} color="red" />
</div>
);
}
export default App;Inline Icon Usage
This feature allows you to use the icon inline with text. Setting the inline property to true makes the icon align with the text.
import { Icon } from '@iconify/react';
import homeIcon from '@iconify-icons/mdi/home';
function App() {
return (
<div>
<Icon icon={homeIcon} inline={true} />
<span>Home</span>
</div>
);
}
export default App;react-icons provides a comprehensive set of icons from various icon libraries such as Font Awesome, Material Design, and more. It is similar to @iconify/react in that it allows you to easily include and customize icons in your React applications. However, react-icons focuses on a curated set of popular icon libraries, whereas @iconify/react supports a broader range of icon sets.
react-fontawesome is a React component library specifically for Font Awesome icons. It allows you to use Font Awesome icons in your React applications with ease. Compared to @iconify/react, react-fontawesome is limited to Font Awesome icons, while @iconify/react supports a wider variety of icon sets.
react-svg is a React component that allows you to import and use SVG files as React components. It provides more flexibility in terms of using custom SVG icons. While @iconify/react focuses on providing a large collection of pre-defined icons, react-svg is more suitable for projects that require custom SVG icons.
Iconify for React is not yet another icon component! There are many of them already.
What you get with other components:
Iconify icon component is nothing like that. Component does not include any icon data, it is not tied to any specific icon set. Instead, all data is retrieved from public API on demand.
That means:
For more information about Iconify project visit https://iconify.design/.
For extended documentation visit Iconify for React documentation.
If you are using NPM:
npm install --save-dev @iconify/react
If you are using Yarn:
yarn add --dev @iconify/react
Install @iconify/react and import Icon from it:
import { Icon } from '@iconify/react';
Then use Icon component with icon name or data 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 100,000 icons available on Iconify API from various free and open source icon sets, including all the most popular icon sets.
Retrieving icon data from Iconify API requires visitor to be online. What if you want to use component offline or on local network?
If you want to use icon component without relying on public Iconify API, there are several options:
See Iconify for React offline use documentation or Iconify API documentation.
Icon name is a string. Few examples:
@api-provider:icon-set-prefix:icon-namemdi-light:home (in this example API provider is empty, so it is skipped)It has 3 parts, separated by ":":
See Iconify for React icon names documentation for more detailed explanation.
Instead of icon name, you can pass icon data to component:
import { Icon } from '@iconify/react';
import home from '@iconify-icons/mdi-light/home';
function renderHomeIcon() {
return <Icon icon={home} />;
}
See icon packages documentation for more details.
Example above will currently fail with Next.js. This is because Next.js uses outdated packaging software that does not support ES modules. But do not worry, there is a simple solution: switch to CommonJS icon packages.
To switch to CommonJS package, replace this line in example above:
import home from '@iconify-icons/mdi-light/home';
with
import home from '@iconify/icons-mdi-light/home';
All icons are available as ES modules for modern bundler and as CommonJS modules for outdated bundlers. ES modules use format @iconify-icons/{prefix}, CommonJS modules use @iconify/icons-{prefix}.
For more details, see icon packages documentation.
Icons have 2 modes: inline and block. Difference between modes is vertical-align that is added to inline icons.
Inline icons are aligned slightly below baseline, so they look centred compared to text, like glyph fonts.
Block icons do not have alignment, like images, which aligns them to baseline by default.
Alignment option was added to make icons look like continuation of text, behaving like glyph fonts. This should make migration from glyph fonts easier.
import React from 'react';
import { Icon, InlineIcon } from '@iconify/react';
export function inlineDemo() {
return (
<div>
<p>
Block:
<Icon icon="line-md:image-twotone" />
<Icon icon="mdi:account-box-outline" />
</p>
<p>
Inline:
<InlineIcon icon="line-md:image-twotone" />
<InlineIcon icon="mdi:account-box-outline" />
</p>
</div>
);
}
To toggle between block and inline modes, you can either use InlineIcon or use boolean inline property:
import React from 'react';
import { Icon } from '@iconify/react';
export function inlineDemo() {
return (
<div>
<p>
Block:
<Icon icon="line-md:image-twotone" />
<Icon icon="mdi:account-box-outline" />
</p>
<p>
Inline:
<Icon icon="line-md:image-twotone" inline={true} />
<Icon icon="mdi:account-box-outline" inline={true} />
</p>
</div>
);
}
Visual example to show the difference between inline and block modes:
icon property is mandatory. It tells component what icon to render. The value can be a string containing the icon name or an object containing the icon data.
The icon component has the following optional properties:
inline. Changes icon behaviour to match icon fonts. See "Inline icon" section above.width and height. Icon dimensions. The default values are "1em" for both. See "Dimensions" section below.color. Icon colour. This is the same as setting colour in style. See "Icon colour" section below.flip, hFlip, vFlip. Flip icon horizontally and/or vertically. See "Transformations" section below.rotate. Rotate icon by 90, 180 or 270 degrees. See "Transformations" section below.align, vAlign, hAlign, slice. Icon alignment. See "Alignment" section below.onLoad. Callback function that is called when icon data has been loaded. See "onLoad" section below.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.
By default, icon height is "1em". With is dynamic, calculated using 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:
font-size in style (or fontSize if you are using inline style).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.
You can use numbers for width and height.
<Icon icon={homeIcon} height={24} />
<Icon icon="mdi-light:home" width={16} height={16} />
Number values are treated as pixels. That means in examples above, values are identical to "24px" and "16px".
If you use strings without units, they are treated the same as numbers in an example above.
<Icon icon={homeIcon} height="24" />
<Icon icon="mdi-light:home" width="16" height={'16'} />
You can use units in width and height values:
<Icon icon="mdi-light:home" height="2em" />
Be careful when using calc, view port based units or percentages. In SVG element they might not behave the way you expect them to behave and when using such units, you should consider settings both width and height.
Keyword "auto" sets dimensions to the icon's viewBox dimensions. For example, for 24 x 24 icon using height="auto" sets height to 24 pixels.
<Icon icon="mdi-light:home" height="auto" />
There are two types of icons: icons that do not have a palette and icons that do have a palette.
Icons that do have a palette, such as emojis, cannot be customised. Setting colour to such icons will not change anything.
Icons that do not have a palette can be customised. By default, colour is set to "currentColor", which means the icon's colour matches text colour. To change the colour you can:
color style or use stylesheet to target icon. If you are using the stylesheet, target svg element.color property.Examples:
Using color property:
<Icon icon="eva:alert-triangle-fill" color="red" />
<Icon icon="eva:alert-triangle-fill" color="#f00" />
Using inline style:
<Icon icon="eva:alert-triangle-fill" style={{color: 'red'}} />
<Icon icon="eva:alert-triangle-fill" style={{color: '#f00'}} />
Using stylesheet:
<Icon icon="eva:alert-triangle-fill" className="red-icon" />
.red-icon {
color: red;
}
You can rotate and flip the icon.
This might seem redundant because icon can also be rotated and flipped using CSS transformations. So why do transformation properties exist? Because it is a different type of transformation.
If you have a square icon, this makes no difference. However, if you have an icon that has different width and height values, it makes a huge difference.
Rotating 16x24 icon by 90 degrees results in:
See icon transformations documentation for more details.
There are several properties available to flip an icon:
hFlip: boolean property, flips icon horizontally.vFlip: boolean property, flips icon vertically.flip: shorthand string property, can flip icon horizontally and/or vertically.Examples:
Flip an icon horizontally:
<Icon icon="eva:alert-triangle-fill" hFlip={true} />
<Icon icon="eva:alert-triangle-fill" flip="horizontal" />
Flip an icon vertically:
<Icon icon="eva:alert-triangle-fill" vFlip={true} />
<Icon icon="eva:alert-triangle-fill" flip="vertical" />
Flip an icon horizontally and vertically (the same as 180 degrees rotation):
<Icon icon="eva:alert-triangle-fill" hFlip={true} vFlip={true} />
<Icon icon="eva:alert-triangle-fill" flip="horizontal,vertical" />
An icon can be rotated by 90, 180 and 270 degrees. Only contents of the icon are rotated.
To rotate an icon, use rotate property. Value can be a string (degrees or percentages) or a number.
Number values are 1 for 90 degrees, 2 for 180 degrees, 3 for 270 degrees.
Examples of 90 degrees rotation:
<Icon icon="eva:alert-triangle-fill" rotate={1} />
<Icon icon="eva:alert-triangle-fill" rotate="90deg" />
<Icon icon="eva:alert-triangle-fill" rotate="25%" />
onLoad property is an optional callback function. It is called when icon data has been loaded.
It is not an event, such as onClick event for links, it is a simple callback function.
When onLoad is called:
onLoad is not called.onLoad is called on first render.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 parent element, such as "container--with-icon" that modify layout if icon is being displayed.
For extended documentation visit Iconify for React documentation.
React component is released with MIT license.
© 2019 - 2022 Vjacheslav Trushkin / Iconify OÜ
See Iconify icon sets page for list of collections and their licenses.
FAQs
Iconify icon component for React.
We found that @iconify/react demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.