To get started you'll need to install the following packages into your project using a package manager like npm(opens new window) and yarn(opens new window). Here are examples that install everything you need and our solid style of icons using each respective package manager.
npm i --save @fortawesome/fontawesome-svg-core
npminstall--save @fortawesome/free-solid-svg-icons
npminstall--save @fortawesome/react-fontawesome
If you want to use additional styles of icons, you'll need to install them as well. Here's an example of how to add our brand icons and the free set of our regular style icons via npm(opens new window).
npm i --save @fortawesome/pro-solid-svg-icons
npm i --save @fortawesome/pro-regular-svg-icons
npm i --save @fortawesome/pro-light-svg-icons
npm i --save @fortawesome/pro-duotone-svg-icons
In order to use Pro icons, you'll need to pass the type of icon you want to use into the icon prop of the component. Read on for more detailed instructions about usage:
// Light:<FontAwesomeIconicon={["fal","coffee"]}/>// Regular:<FontAwesomeIconicon={["far","coffee"]}/>// Solid<FontAwesomeIconicon={["fas","coffee"]}/>// ...or, omit as FontAwesome defaults to solid, so no need to prefix:<FontAwesomeIconicon="coffee"/>// Brand:<FontAwesomeIconicon={["fab","github"]}/>
This package, under the hood, uses SVG with JS and the @fortawesome/fontawesome-svg-core library. This implementation differs drastically from the classic Web Font-based one in Font Awesome 4 and earlier. If you want to know the details, read up on fontwesome-svg-core. If you're coming from Version 4, we also recommend learning more about upgrading to Font Awesome 5 in general.
Using Icons
Advertisement
Remove ads with a Pro plan!
A subscription to a Pro-level plan will remove all third-party advertisements on fontawesome.com.
And of course Pro-level plans come with…
All 7,864 icons in Font Awesome
5 Classic styles of every icon
3 Sharp styles of every icon
A Perpetual License to use Pro
Services and tools to make easy work of using icons
Once you've installed all the packages you need for your project, there are two ways you can use Font Awesome 5 with React. Here's a summary of both options as well as their benefits and possible drawbacks.
Option
Benefits
Drawbacks
Individual Use
Allows icons to be subsetted, optimizing your final bundle. Only the icons you import are included in the bundle.
Explicitly importing icons into each of many components in your project can become tedious.
Global Use
Individually import icons just once in an init module - there's no need to import the icons into each component once they’ve been added to the library.
You may be including files that won't be used and could impact performance.
Using Icons via Individual Use
Again, with this method, you'll need to explicitly import icons into each component. Here's a simple example.
Notice that the faCoffee icon is imported from
@fortawesome/free-solid-svg-icons as an object and then provided to the
icon prop as an object.
Also, for the above example, we're referencing the @fortawesome/free-solid-svg-icons module, so make sure you've already installed that package in your project.
Using Icons via Global Use
You probably want to use our icons in more than one component in your project, right? Importing icons into each of your project's components can be really tedious and prone to display errors - especially over time.
Instead, you can add them once in your React application and reference them in any component. We recommend importing them via a "library" in the initializing module of your React application. Here's an example...
Let's say you have a React Application, "Coffee Checker", that alerts users when recently brewed coffee has been sitting around too long and freshness is compromised.
We use Coffee Checker's App.js to initialize our app and library. Our app's UI wants to use two individual icons, faCheckSquare and faCoffee. We also add all of the brands in @fortawesome/free-brands-svg-icons to build the showcase of the big companies that fictitiously use "Coffee Checker" over time.
fab: which represents all of the brand icons in
@fortawesome/free-brands-svg-icons.
So any of the brand icons in that package may be referenced by icon name
as a string anywhere else in our app.
For example: "apple", "microsoft", or "google".
faCheckSquare and faCoffee: Adding each of these icons individually
allows us to refer to them throughout our app by their icon string names,
"check-square" and "coffee", respectively.
Our application also has React components, Beverage and Showcase. After initializing the above library, you don't have to re-import icons into each of them. We import the FontAwesomeIcon component, and when used, you supply the icon prop an icon name as a string. Here's how that looks in our functional component, Beverage.js:
import React from'react'import{ FontAwesomeIcon }from'@fortawesome/react-fontawesome'exportconstBeverage=()=>(<div><FontAwesomeIconicon="check-square"/>
Your <FontAwesomeIconicon="coffee"/> is hot and ready!
</div>)
Heads Up: Solid is the Default Style
There's one another piece of magic that's happening in the background when providing icon names as strings like this: the fas prefix (for Font Awesome Solid) is being inferred as the default.
And here's the Showcase.js component:
import React from'react'import{ FontAwesomeIcon }from'@fortawesome/react-fontawesome'exportconstShowcase=()=>(<div><FontAwesomeIconicon={['fab','apple']}/><FontAwesomeIconicon={['fab','microsoft']}/><FontAwesomeIconicon={['fab','google']}/><FontAwesomeIconicon="check-square"/>
With Coffee Checked, these companies always know their coffee is hot and ready!
</div>)
We used the "check-square" icon name again in this component, though you
didn't have to explicitly import it into this component thanks to the previous import and library addition in our App.js.
The "check-square" icon is getting a default prefix of fas here too, which is what you want, because that icon also lives in the @fortawesome/free-solid-svg-icons package.
We used the "apple", "microsoft", and "google" brand icons, which were
never explicitly individually imported, but they're available to us by
name as strings because all brand icons were added to our library in App.js, and
fab includes all of those icons.
We added the Brands-specific fab style prefix to reference those 3 brand icons.
Icon Syntax
Advertisement
Remove ads with a Pro plan!
A subscription to a Pro-level plan will remove all third-party advertisements on fontawesome.com.
And of course Pro-level plans come with…
All 7,864 icons in Font Awesome
5 Classic styles of every icon
3 Sharp styles of every icon
A Perpetual License to use Pro
Services and tools to make easy work of using icons
As our examples above show, the syntax to reference an icon in the above components is different than our traditional HTML-based syntax. These are all valid ways to define the icon prop:
It could a string object, like "coffee". (The curly braces around a string object supplied to a prop are optional, so they were omitted.)
Or it could be an Array of strings, where the first element is a style prefix, and the second element is the icon name: {["fab", "apple"]}
More About Styles + Prefixes
We added more styles in Font Awesome 5 and are using prefixes to call specific ones when rendering icons. Check out our complete list of styles to see what's available in Font Awesome Free and Pro.
Features
All of the style toolkit features available for general web use are also available in the official Font Awesome React component. Note, however, that the syntax is different from our general web-use documentation.
We're Using Shortcuts Below
In the following code snippets, you'll use the shortcut notation for the icons—referencing the icons by their names as strings. But remember, that option is only valid after you've either explicitly imported and added those icons to the library, or externally loaded an icon bundle. See the sections above for the details.
Note that icon size can be controlled with the CSS font-size attribute, and FontAwesomeIcon's size prop determines icon size relative to the current font-size.
When testing components, you'll want to make sure that any icons referenced in those components are available for testing purposes. You have a couple choices here:
If you want to test a child component on its own, you can import its icons explicitly.
If you've built a library instead, and your test doesn't include your root component that defines your library of icons, you may see errors like this:
Could not find icon { prefix: 'fas', iconName: 'chevron-right' }
If this happens, and the icon isn't important to the particular test, you can mock FontAwesomeIcon like this:
With create-react-app(opens new window), you can put this code in src/__mocks__/@fortawesome/react-fontawesome.js to automatically include it in any tests, and alleviate errors.
Processing <i> Elements into SVG using Font Awesome
Our hope and intention is that React users will use this package (react-fontawesome) when using Font Awesome. This component leverages React's architecture and philosophy. If you cannot use these components everywhere in your app and still have <i> tags on your page that need to be converted to <svg> tags we can
still help you.
When using the @fortawesome/fontawesome-svg-core package this behavior is disabled by default. (We would highly recommend you use FontAwesomeIcon if you can) This project uses that core package so you will have to explicitly enable it like this:
To configure the core library to convert non-React'ified parts of your App:
import{ dom }from'@fortawesome/fontawesome-svg-core'
dom.watch()// This will kick of the initial replacement of i to svg tags and configure a MutationObserver
TypeScript
Advertisement
Remove ads with a Pro plan!
A subscription to a Pro-level plan will remove all third-party advertisements on fontawesome.com.
And of course Pro-level plans come with…
All 7,864 icons in Font Awesome
5 Classic styles of every icon
3 Sharp styles of every icon
A Perpetual License to use Pro
Services and tools to make easy work of using icons
Typings are included in this package. However, most types are defined in the underlying API library, @fortawesome/fontawesome-svg-core. Suppose that in one module, you add all fas icons to the library:
Then suppose that in another module, you have some code that looks up one of the icons in the library. The import statement below imports two types and one function:
You wouldn't normally declare intermediate objects like coffeeLookup just to look up an icon. So this is cumbersome and needlessly verbose for such a simple example. The purpose here is just to show how you might import type definitions and use them in declarations when it does make sense to do so.
Several types, including IconLookup and IconDefinition, appearing above, actually originate from the @fortawesome/fontawesome-common-types package. They are re-exported from both @fortawesome/fontawesome-svg-core and @fortawesome/free-solid-svg-icons (and other icon packs). This is just to make importing more convenient in some cases. Refer to the index.d.ts in any module to see which types it exports.
Next.js
The react-fontawesome component integrates well with Next.js but there is one caveat you need to solve.
Since Next.js manages CSS differently than most web projects if you just follow the plain vanilla documentation to integrate react-fontawesome into your project you'll see huge icons because they are missing the accompanying CSS that makes them behave.
Getting Font Awesome CSS to work
Let's assume that you have a standard install and that pages is in the root.
To do this you'll start by creating a pages/_app.js. If you already have one, you can modify it so that it includes the extra bits you need.
It's also a good idea to [check the Next.js documentation on creating a custom 'App'(opens new window). There's a chance that something has changed with that project and the export default ... part needs to change.
Next.js allows you to import CSS directly in .js files. It handles optimization and all the necessary Webpack configuration to make this work.
You change this configuration value to false so that the Font Awesome core SVG library will not try and insert <style> elements into the <head> of the page. Next.js blocks this from happening anyway so you might as well not even try.
config.autoAddCss =false
Using Icons in Pages
import Head from'next/head'import{ FontAwesomeIcon }from'@fortawesome/react-fontawesome'import{ faFaceRelieved }from'@fortawesome/pro-solid-svg-icons'exportdefaultfunctionHome(){return(<divclassName="container"><main><h1className="title"><FontAwesomeIconicon={faFaceRelieved}/>
Welcome to <ahref="https://nextjs.org">Next.js!</a></h1></main></div>)}
Troubleshooting with Next.js
Failed to import ./styles.css
Module not found: Package path ./styles.css is not exported from package`
Newer versions of Next.js may give you this error. A workaround is to change the way the styles are imported.
We'll be making some changes to our version 6 packages that use the new exports property on the package.json file to fix this in the future.
Duotone Icons Aren't Working
If you attempt to use our duotone icons and they look more like our solid icons, it probably means that the CSS for Font Awesome has not been installed.
Along with properly sizing icons, the CSS for Font Awesome is also responsible for setting the opacity for the secondary layer which is how these icons work.
FAQs
Advertisement
Remove ads with a Pro plan!
A subscription to a Pro-level plan will remove all third-party advertisements on fontawesome.com.
And of course Pro-level plans come with…
All 7,864 icons in Font Awesome
5 Classic styles of every icon
3 Sharp styles of every icon
A Perpetual License to use Pro
Services and tools to make easy work of using icons
I'm getting a Babel/Babel-loader error when using React Font Awesome
If you're using a Mac or Linux, make sure you are up to date on the latest versions by running brew update & brew upgrade. Or delete your package.json.lock file & Node_Modules folder and then run either npm install or yarn install to reinstall all packages and dependencies.
Useful Links
The Font Awesome React component is available on npm and that's also where we maintain its official documentation.