Learn about our new SVG implementation

This package, under the hood, uses SVG with JS and the @fortawesome/fontawesome-svg-core library. This implementation differs drastically from
the web fonts implementation that was used in version 4 and older of Font Awesome. You might head over there to learn about how it works.

or with Yarn

Usage

You can use Font Awesome icons in your React components as simply as this:

<FontAwesomeIcon icon="coffee"/>

That simple usage is made possible when you add the "coffee" icon, to the
library.

This is one of the two ways you can use Font Awesome 5 with React. We'll
summarize both ways briefly and then get into the details of each below.

Explicit Import

Allows icons to be subsetted, optimizing your final bundle. Only the icons
you import are included in the bundle. However, explicitly importing icons
into each of many components in your app might become tedious, so you may
want to build a library.

Build a Library

Explicitly import icons just once in some init module. Then add them to the
library. Then reference any of them by icon name as a string from any
component. No need to import the icons into each component once they're in
the library.

Explicit Import

For this example, we'll also reference the @fortawesome/free-solid-svg-icons
module, so make sure you've added it to the project as well:

$ npm i --save @fortawesome/free-solid-svg-icons

or

$ yarn add @fortawesome/free-solid-svg-icons

Now, a simple React component might look like this:

importReactDOMfrom'react-dom'

import{FontAwesomeIcon}from'@fortawesome/react-fontawesome'

import{faCoffee}from'@fortawesome/free-solid-svg-icons'

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

Explicitly importing icons like this allows us to subset Font Awesome's
thousands of icons to include only those you use in your final bundled file.

Build a Library to Reference Icons Throughout Your App More Conveniently

You probably want to use our icons in more than one component in your app,
right?

But with explicit importing, it could become tedious to import into each of
your app's components every icon you want to reference in that component.

So, add them to the library. Do this setup once in some initializing module
of your app, adding all of the icons you'll use in your app's React components.

Suppose App.js initializes my app, including the library. For this example,
we'll add two individual icons, faCheckSquare and faCoffee. We also add all
of the brands in @fortawesome/free-brands-svg-icons. This example would
illustrate the benefits of building a library even more clearly if it involved
fifty or a hundred icons, but we'll keep the example brief and leave it to your
imagination as to how this might scale up with lots of icons.

Don't forget to add @fortawesome/free-brands-svg-icons:

$ npm i --save @fortawesome/free-brands-svg-icons

or

$ yarn add @fortawesome/free-brands-svg-icons

In App.js, where our app is initialized:

importReactDOMfrom'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)

OK, so what's happening here?

In our call to library.add() we'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.

Now, suppose you also have React components Beverage and Gadget in your app.
You don't have to re-import your icons into them. Just import the FontAwesomeIcon
component, and when you use it, supply the icon prop an icon name as a string.

We'll make Beverage.js a functional component:

importReactfrom'react'

import{FontAwesomeIcon}from'@fortawesome/react-fontawesome'

exportconstBeverage=()=>(

<div>

<FontAwesomeIcon icon="check-square"/>

Favorite beverage:<FontAwesomeIcon icon="coffee"/>

</div>

)

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. Later, we'll look at what that means
and how we can do something different than the default.

Now suppose Gadget.js looks like this:

importReactfrom'react'

import{FontAwesomeIcon}from'@fortawesome/react-fontawesome'

exportconstGadget=()=>(

<div>

<FontAwesomeIcon icon="check-square"/>

Popular gadgets come from vendors like:

<FontAwesomeIcon icon={['fab','apple']}/>

<FontAwesomeIcon icon={['fab','microsoft']}/>

<FontAwesomeIcon icon={['fab','google']}/>

</div>

)

Notice:

We used the "check-square" icon name again in this component, though we
didn't have to explicitly import it into this component. With one explicit import of
that icon in App.js, and adding it to the library, we've managed to use
it by name in multiple components.

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 fab was added to our library in App.js, and
fab includes all of those icons.

We added the fab prefix to reference those brand icons.

Adding a prefix—and the syntax we used to do it—are new. So what's
going on here?

First, recall when we introduced <FontAwesomeIcon icon="coffee"/> and learned
that a prefix of fas was being added to "coffee" by default.

The "check-square" icon is getting a default prefix of fas here too, which
is what we want, because that icon also lives in the
@fortawesome/free-solid-svg-icons package.

However, the "apple", "microsoft", and "google" brand icons live in the
package @fortawesome/free-brands-svg-icons. So we need to specify a
different prefix for them—not the default fas, but fab, for Font Awesome
Brand.

When specifying a prefix with an icon name, both are given as strings.

Now, what about that syntax?

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 we've omitted them.)

Or it could be an Array of strings, where the first element is a prefix,
and the second element is the icon name: {["fab", "apple"]}

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:

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

Features

The following features are available as part of Font Awesome. Note that the syntax is different from our general web-use documentation.

In the following code snippets, we'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: 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.

How to Help

Contributors

The following contributors have either hepled to start this project, have contributed
code, are actively maintaining it (including documentation), or in other ways
being awesome contributors to this project. We'd like to take a moment to recognize them.