• Sage

How to Use Font Awesome 5 in Sage

Use Font Awesome 5 in a Sage 9 theme, loading SVGs via the advanced JavaScript API to take advantage of tree shaking.

(Tree shaking is a code optimization process that trims unused pieces from bundled assets. In other words, if you only use two icons, all the other ones will be removed when you run yarn build:production.)


If you just want to get Font Awesome up and running as quickly and easily as possible…
… then this method is not for you. Instead, load Font Awesome from their CDN and put the desired icons in your markup.


Install the packages

Install the core package (provides the functionality but not any icons):

yarn add @fortawesome/fontawesome-svg-core

And one or more icon sets, depending on which icons you want:

yarn add @fortawesome/free-solid-svg-icons
yarn add @fortawesome/free-regular-svg-icons
yarn add @fortawesome/free-brands-svg-icons
yarn add @fortawesome/pro-solid-svg-icons
yarn add @fortawesome/pro-regular-svg-icons
yarn add @fortawesome/pro-light-svg-icons

Want to use the pro packages? See the final section of this guide.

Set up the icons in your JavaScript

Wherever you prefer in your JS, import the needed modules. Unless you’re going to be using a lot of icons, it’s probably best to import the specific icons you’ll use.

For example, we’ll import the Facebook and Twitter icons in main.js:

// import then needed Font Awesome functionality
import { library, dom } from '@fortawesome/fontawesome-svg-core';
// import the Facebook and Twitter icons
import { faFacebook, faTwitter } from "@fortawesome/free-brands-svg-icons";

// add the imported icons to the library
library.add(faFacebook, faTwitter);

// tell FontAwesome to watch the DOM and add the SVGs when it detects icon markup
dom.watch();

You can also import an entire icon set at once, but that will result in a much larger bundle for your users to download. If you’ve thought through the performance implications and you have a good reason to do it anyway, see here.

Add the icon markup to your templates

In the appropriate template file:

<!-- Facebook icon -->
<i class="fab fa-facebook"></i>
<!-- Twitter icon -->
<i class="fab fa-twitter"></i>

Build

Finally, run yarn build.


Using the Pro Icon Sets

If you want to use the pro icon sets, you’ll need to set your authorization token. You can do this globally, so that it is available to all your projects, or locally, so that it is available for a specific project.

In both examples below, replace your-token-here with your actual auth token.

Globally

npm config set "@fortawesome:registry" https://npm.fontawesome.com/ \
npm config set "//npm.fontawesome.com/:_authToken" your-token-here

Locally
Add a .npmrc file to the root of your project with the following:

@fortawesome:registry=https://npm.fontawesome.com/
//npm.fontawesome.com/:_authToken=your-token-here

You can find both your token and more docs on using the pro version here. Note that this page of the docs is talking about a different method of using FontAwesome, so only pay attention to the instructions on adding your auth token.

Related docs

Join the discussion on Roots Discourse

Join over 5,600 subscribers on our newsletter to get the latest Roots updates, along with occasional tips on building better WordPress sites.

Looking for WordPress plugin recommendations, the newest modern WordPress projects, and general web development tips and articles?

“Easily the best WordPress email I get.” Colin OBrien

Ready to checkout?