React

Font Awesome now has an official React component that’s available for a friction-less way to use our icons in your React applications.

Before You Get Started

Make sure you:

• want to use React and not React Native (which is a different react-native-fontawesome component).
• are okay with using SVG + JS to render icons in your project - this react component relies on that technology
• Downloaded the Font Awesome v5 web-specific files and have them handy.
• Have a project set up set up to use Pro packages if you plan on using Pro-only icons.

Get Started

To get started you’ll need to install the following packages into your project using a package manager like npm and yarn. Here are examples that install everything you need and our solid style of icons using each respective package manager.

npm

npm i --save @fortawesome/fontawesome-svg-core
npm install --save @fortawesome/free-solid-svg-icons
npm install --save @fortawesome/react-fontawesome

yarn

yarn add @fortawesome/fontawesome-svg-core
yarn add @fortawesome/free-solid-svg-icons
yarn add @fortawesome/react-fontawesome

See this Stack Overflow question on the difference between --save and --save-dev. Yarn also lets you use --dev to save as a development dependency.

Adding Additional Styles

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.

npm

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

yarn

yarn add @fortawesome/pro-solid-svg-icons
yarn add @fortawesome/pro-regular-svg-icons
yarn add @fortawesome/pro-light-svg-icons
yarn add @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:
<FontAwesomeIcon icon={["fal", "coffee"]} />
// Regular:
<FontAwesomeIcon icon={["far", "coffee"]} />
// Solid
<FontAwesomeIcon icon={["fas", "coffee"]} />
// ...or, omit as FontAwesome defaults to solid, so no need to prefix:
<FontAwesomeIcon icon="coffee" />
// Brand:
<FontAwesomeIcon icon={["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

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.

import ReactDOM from 'react-dom'
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
import { faCoffee } from '@fortawesome/free-solid-svg-icons'

const element = <FontAwesomeIcon icon={faCoffee} />

ReactDOM.render(element, document.body)

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.

import ReactDOM from 'react-dom'
import { library } from '@fortawesome/fontawesome-svg-core'
import { fab } from '@fortawesome/free-brands-svg-icons'
import { faCheckSquare, faCoffee } from '@fortawesome/free-solid-svg-icons'

library.add(fab, faCheckSquare, faCoffee)

In our call to library.add() you’re passing:

• 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'

export const Beverage = () => (
  <div>
    <FontAwesomeIcon icon="check-square" />
    Your <FontAwesomeIcon icon="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'

export const Showcase = () => (
  <div>
    <FontAwesomeIcon icon={['fab', 'apple']} />
    <FontAwesomeIcon icon={['fab', 'microsoft']} />
    <FontAwesomeIcon icon={['fab', 'google']} />

    <FontAwesomeIcon icon="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

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:

<FontAwesomeIcon icon="coffee" />
<FontAwesomeIcon icon={['fas', 'coffee']} />
<FontAwesomeIcon icon={['far', 'coffee']} />
<FontAwesomeIcon icon={faCoffee} />

The icon prop expects a single object:

• It could be an icon object, like {faCoffee}.
• 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.

Sizing

<FontAwesomeIcon icon="coffee" size="xs" />
<FontAwesomeIcon icon="coffee" size="lg" />
<FontAwesomeIcon icon="coffee" size="6x" />

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.

Fixed-Width Icons

<FontAwesomeIcon icon="coffee" fixedWidth />

Inverse

<FontAwesomeIcon icon="coffee" inverse />

Icons in a List

<FontAwesomeIcon icon="coffee" listItem />
<FontAwesomeIcon icon="coffee" listItem />
<FontAwesomeIcon icon="coffee" listItem />

Rotating Icons

<FontAwesomeIcon icon="coffee" rotation={90} />
<FontAwesomeIcon icon="coffee" rotation={180} />
<FontAwesomeIcon icon="coffee" rotation={270} />

Flip Horizontally, Vertically, or Both

<FontAwesomeIcon icon="coffee" flip="horizontal" />
<FontAwesomeIcon icon="coffee" flip="vertical" />
<FontAwesomeIcon icon="coffee" flip="both" />

Animating Icons

<FontAwesomeIcon icon="spinner" spin />
<FontAwesomeIcon icon="spinner" pulse />

Bordered Icons

<FontAwesomeIcon icon="coffee" border />

Pulled Icons

<FontAwesomeIcon icon="coffee" pull="left" />
<FontAwesomeIcon icon="coffee" pull="right" />

Swap Duotone Icon Layer Opacity

<FontAwesomeIcon icon={['fad', 'coffee']} />
<FontAwesomeIcon icon={['fad', 'coffee']} swapOpacity />

Adding Classes Yourself

You can add classes for your own project purposes and styling to any component using the className property.

<FontAwesomeIcon icon="spinner" className="highlight" />

Power Transforms

<FontAwesomeIcon icon="coffee" transform="shrink-6 left-4" />
<FontAwesomeIcon icon="coffee" transform={{ rotate: 42 }} />

Masking Icons

<FontAwesomeIcon icon="coffee" mask={['far', 'circle']} />

Layering Icons

<span className="fa-layers fa-fw">
  <FontAwesomeIcon icon="square" color="green" />
  <FontAwesomeIcon icon="check" inverse transform="shrink-6" />
</span>

Using SVG Symbols

<FontAwesomeIcon icon="coffee" symbol />
<FontAwesomeIcon icon="coffee" symbol="beverage-icon" />

---

Unit Testing

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:

1. If you want to test a child component on its own, you can import its icons explicitly.

2. 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:

import React from 'react'

export function FontAwesomeIcon(props) {
  return <i className="fa" />
}

With create-react-app, 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.

A basic installation of Font Awesome has the ability to automatically transform <i class="fas fa-coffee"></i> into <svg class="...">...</svg> icons. This technology works with the browser’s DOM, requestAnimationFrame, and MutationObserver.

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

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:

import { library } from '@fortawesome/fontawesome-svg-core'
import { fas } from '@fortawesome/free-solid-svg-icons'

library.add(fas)

// ...

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:

import {
  IconLookup,
  IconDefinition,
  findIconDefinition
} from '@fortawesome/fontawesome-svg-core'

const coffeeLookup: IconLookup = { prefix: 'fas', iconName: 'coffee' }
const coffeeIconDefinition: IconDefinition = findIconDefinition(coffeeLookup)

// ...

export class App extends React.Component {
  render() {
    return (
      <div className="App">
        <h1>
          <FontAwesomeIcon icon={coffeeIconDefinition} />
        </h1>
      </div>
    )
  }
}

For Demo Purposes Only

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.

import { config } from '@fortawesome/fontawesome-svg-core'
import '@fortawesome/fontawesome-svg-core/styles.css'
config.autoAddCss = false

export default function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}

It’s also a good idea to [check the Next.js documentation on creating a custom ‘App’. 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.

import '@fortawesome/fontawesome-svg-core/styles.css'

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'

export default function Home() {
  return (
    <div className="container">
      <main>
        <h1 className="title">
          <FontAwesomeIcon icon={faFaceRelieved} />
          Welcome to <a href="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.

import '../node_modules/@fortawesome/fontawesome-svg-core/styles.css'

This hacky workaround is temporary

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

How do I import the same icon from two different styles?

Using ES modules and import statements you can define unique names for two different styles of the same icon. Here’s an example:

import { library } from '@fortawesome/fontawesome-svg-core'
import { faCoffee as fasFaCoffee } from '@fortawesome/pro-solid-svg-icons'
import { faCoffee as farFaCoffee } from '@fortawesome/pro-regular-svg-icons'

library.add(fasFaCoffee, farFaCoffee)

Haallp! I don’t think tree-shaking is working.

We have detailed documentation on tree-shaking within our API-focused docs.

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.

Useful Link	What it’s good for
API docs	The official React component documentation
GitHub project	Where to submit issues and collaborate/contribute to codebase