Skip to content
Font Awesome Docs: Version 5

Install Manually

This documentation describes customizing WordPress by adding PHP code to your theme’s functions.php file. It’s intended to be used by more advanced WordPress users who know why using our plugin isn’t the best solution for their situation.

If you’re just trying to setup Font Awesome in WordPress the simplest way, with all the magic already built-in, then use our WordPress plugin instead.

CDN vs. Kit

These examples and code snippets offer two different approaches to setting up Font Awesome in WordPress: with kits and without kits. The “without kits” approach is referred to as “CDN” in these examples mainly for legacy reasons. Namely, before we had kits, the options were either to host the icon assets yourself (self-hosting), or load them from our Free or Pro CDN. Then we added kits, which are also backed by a CDN.

So don’t think that the kits approach in these examples is sans-CDN. Kits are backed by a fast and stable CDN.

In fact, kits are usually the best approach you can take for both performance and flexibility, especially Pro kits, especially especially SVG Pro kits. Once you’ve set up a kit with one of these code snippets, you’ll be able to configure and re-configure that kit right from your Font Awesome kit settings and not have to touch the PHP code again.

The “CDN” alternatives are offered because, sometimes, there are use cases where loading the Font Awesome assets directly from the CDN is preferable to loading a kit. But if you aren’t sure that you have such a use case on your hands, then that’s a pretty good clue that setting up a kit is your best bet.

Set up for a Kit

First we’ll lay a foundation with this function that you’ll call with your Kit embed code. If you’re not a coder, don’t worry. You’ll probably never need to modify the code in this function. You’ll only tweak the simpler code below to add your Kit token. Here we go. Copy and paste this into your functions.php:

/**
 * Font Awesome Kit Setup
 *
 * This will add your Font Awesome Kit to the front-end, the admin back-end,
 * and the login screen area.
 */
if (! function_exists('fa_custom_setup_kit') ) {
  function fa_custom_setup_kit($kit_url = '') {
    foreach ( [ 'wp_enqueue_scripts', 'admin_enqueue_scripts', 'login_enqueue_scripts' ] as $action ) {
      add_action(
        $action,
        function () use ( $kit_url ) {
          wp_enqueue_script( 'font-awesome-kit', $kit_url, [], null );
        }
      );
    }
  }
}

Next, you’ll need to add the following code, also to your functions.php, replacing the 42deadbeef.js with your real Kit token, which you can find in your Kit settings.

fa_custom_setup_kit('https://kit.fontawesome.com/42deadbeef.js');

Set up SVG with CDN

First we’ll lay a foundation with this function that you’ll call one or more times to set up the bits and pieces of Font Awesome that you choose.

If you’re not a coder, don’t worry. Any code changes you’ll need to make will be limited to the less complex parts below. You’ll probably never need to modify the code in this function. Instead, you’ll achieve your customization by calling this function one or more times with various arguments.

So it’s a big chunk of copy-and-paste, but the hand-coding requirements will be super-minimal. Just wait, you’ll see.

OK, now copy this chunk and paste it into your functions.php:

/**
  * Font Awesome CDN Setup SVG
  *
  * This will load Font Awesome 5 from the Font Awesome Free or Pro CDN.
  */
if (! function_exists('fa_custom_setup_cdn_svg') ) {
  function fa_custom_setup_cdn_svg($cdn_url = '', $integrity = null) {
    $matches = [];
    $match_result = preg_match('|/([^/]+?)\.js$|', $cdn_url, $matches);
    $resource_handle_uniqueness = ($match_result === 1) ? $matches[1] : md5($cdn_url);
    $resource_handle = "font-awesome-cdn-svg-$resource_handle_uniqueness";


    foreach ( [ 'wp_enqueue_scripts', 'admin_enqueue_scripts', 'login_enqueue_scripts' ] as $action ) {
      add_action(
        $action,
        function () use ( $cdn_url, $resource_handle ) {
          wp_enqueue_script( $resource_handle, $cdn_url, [], null );
        }
      );
    }


    if($integrity) {
      add_filter(
        'script_loader_tag',
        function( $html, $handle ) use ( $resource_handle, $integrity ) {
          if ( in_array( $handle, [ $resource_handle ], true ) ) {
            return preg_replace(
              '/^<script /',
              '<script integrity="' . $integrity .
              '" defer crossorigin="anonymous"',
              $html,
              1
            );
          } else {
            return $html;
          }
        },
        10,
        2
      );
    }
  }
}

Load All Styles

Use the CDN Picker to figure out which CDN URLs and integrity keys you want to use. Make sure you have selected “SVG”.

For example, if you were to choose “All” for Font Awesome Free version 5.15.4, this is what you’d get:

<script defer src="https://use.fontawesome.com/releases/v5.15.4/js/all.js" integrity="sha384-rOA1PnstxnOBLzCLMcre8ybwbTmemjzdNlILg8O7z1lUkLXozs4DHonlDtnE7fpc" crossorigin="anonymous"></script>

Here is the corresponding PHP code to copy and paste into your functions.php:

fa_custom_setup_cdn_svg(
  'https://use.fontawesome.com/releases/v5.15.4/js/all.js',
  'sha384-rOA1PnstxnOBLzCLMcre8ybwbTmemjzdNlILg8O7z1lUkLXozs4DHonlDtnE7fpc'
);

The first function argument corresponds to the src attribute fromthe <script> element provided by the CDN Picker. It’s required.

The second argument corresponds to the integrity attribute from the CDN Picker. It’s optional. It’s a security feature that tells the web browser how to verify that the file is exactly the expected file and has not been tampered with.

If you want to change the version you’re loading in WordPress, go back to the CDN Picker and use it to select the new version. Then use the resulting src and integrity attributes to update the arguments to fa_custom_setup_cdn_svg() in your functions.php.

Load a Subset of Styles

If you want to load a subset of styles, instead of all.js, use the CDN Picker to select the styles you want, and then translate each resulting <script> into a separate invocation of fa_custom_setup_cdn_svg() in your functions.php.

Note that when choosing specific styles, there will be always be one additonal <script> that loads the base fontawesome.js, which is required.

For example, if you wanted to load only the Solid style for Font Awesome Free version 5.15.4, you’d get this from the CDN Picker:

  <script defer src="https://use.fontawesome.com/releases/v5.15.4/js/solid.js" integrity="sha384-/BxOvRagtVDn9dJ+JGCtcofNXgQO/CCCVKdMfL115s3gOgQxWaX/tSq5V8dRgsbc" crossorigin="anonymous"></script>
  <script defer src="https://use.fontawesome.com/releases/v5.15.4/js/fontawesome.js" integrity="sha384-dPBGbj4Uoy1OOpM4+aRGfAOc0W37JkROT+3uynUgTHZCHZNMHfGXsmmvYTffZjYO" crossorigin="anonymous"></script>
fa_custom_setup_cdn_svg(
  'https://use.fontawesome.com/releases/v5.15.4/js/solid.js',
  'sha384-/BxOvRagtVDn9dJ+JGCtcofNXgQO/CCCVKdMfL115s3gOgQxWaX/tSq5V8dRgsbc'
);


fa_custom_setup_cdn_svg(
  'https://use.fontawesome.com/releases/v5.15.4/js/fontawesome.js',
  'sha384-dPBGbj4Uoy1OOpM4+aRGfAOc0W37JkROT+3uynUgTHZCHZNMHfGXsmmvYTffZjYO'
);

Load the V4 Shims

You can also add version 4 compatibility with the v4 shims, if needed.

You should use the same version for the shims as you use for the main assets (such as either all.js, or some combination of fontawesome.js and styles like duotone.js, as shown above).

Since all of our examples above use version 5.15.4, we’ll stick with that version in this example too. This PHP should be added to your functions.php in addition to the code you add to load the main Font Awesome assets.

fa_custom_setup_cdn_svg(
  'https://use.fontawesome.com/releases/v5.15.4/js/v4-shims.js'
);

Setup Webfont with CDN

Load Font Awesome’s Webfont and CSS assets directly from our Free or Pro CDNs. First we’ll lay a foundation with this function that you’ll call one or more times to set up the bits and pieces of Font Awesome that you choose.

If you’re not a coder, don’t worry. Any code changes you’ll need to make will be limited to the less complex parts below. You’ll probably never need to modify the code in this function. Instead, you’ll achieve your customization by calling this function one or more times with various arguments.

So it’s a big chunk of copy-and-paste, but the hand-coding requirements will be super-minimal. Just wait, you’ll see.

/**
 * Font Awesome CDN Setup Webfont
 *
 * This will load Font Awesome from the Font Awesome Free or Pro CDN.
 */
if (! function_exists('fa_custom_setup_cdn_webfont') ) {
  function fa_custom_setup_cdn_webfont($cdn_url = '', $integrity = null) {
    $matches = [];
    $match_result = preg_match('|/([^/]+?)\.css$|', $cdn_url, $matches);
    $resource_handle_uniqueness = ($match_result === 1) ? $matches[1] : md5($cdn_url);
    $resource_handle = "font-awesome-cdn-webfont-$resource_handle_uniqueness";


    foreach ( [ 'wp_enqueue_scripts', 'admin_enqueue_scripts', 'login_enqueue_scripts' ] as $action ) {
      add_action(
        $action,
        function () use ( $cdn_url, $resource_handle ) {
          wp_enqueue_style( $resource_handle, $cdn_url, [], null );
        }
      );
    }


    if($integrity) {
      add_filter(
        'style_loader_tag',
        function( $html, $handle ) use ( $resource_handle, $integrity ) {
          if ( in_array( $handle, [ $resource_handle ], true ) ) {
            return preg_replace(
              '/\/>$/',
              'integrity="' . $integrity .
              '" crossorigin="anonymous" />',
              $html,
              1
            );
          } else {
            return $html;
          }
        },
        10,
        2
      );
    }
  }
}

Load All Styles

Use the CDN Picker to figure out which CDN URLs and integrity keys you want to use. Make sure you have selected “Webfont”.

For example, if you were to choose “All” for Font Awesome Free version 5.15.4, this is what you’d get:

<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.15.4/css/all.css" integrity="sha384-DyZ88mC6Up2uqS4h/KRgHuoeGwBcD4Ng9SiP4dIRy0EXTlnuz47vAwmeGwVChigm" crossorigin="anonymous"/>

Here is the corresponding PHP code to copy and paste into your functions.php:

fa_custom_setup_cdn_webfont(
  'https://use.fontawesome.com/releases/v5.15.4/css/all.css',
  'sha384-DyZ88mC6Up2uqS4h/KRgHuoeGwBcD4Ng9SiP4dIRy0EXTlnuz47vAwmeGwVChigm'
);

The first function argument corresponds to the href attribute from the <link> element provided by the CDN Picker. It’s required.

The second argument corresponds to the integrity attribute from the CDN Picker. It’s optional. It’s a security feature that tells the web browser how to verify that the file is exactly the expected file and has not been tampered with.

If you want to change the version you’re loading in WordPress, go back to the CDN Picker and use it to select the new version. Then use the resulting href and integrity attributes to update the arguments to fa_custom_setup_cdn_webfont() in your functions.php.

Load a Subset of Styles

If you want to load a subset of styles, instead of all.css, use the CDN Picker to select the styles you want, and then translate each resulting <link> into a separate invocation of fa_custom_setup_cdn_webfont() in your functions.php.

Note that when choosing specific styles, there will be always be one additonal <link> that loads the base fontawesome.css, which is required.

For example, if you wanted to load only the Solid style for Font Awesome Free version 5.15.4, you’d get this from the CDN Picker:

  <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.15.4/css/solid.css" integrity="sha384-Tv5i09RULyHKMwX0E8wJUqSOaXlyu3SQxORObAI08iUwIalMmN5L6AvlPX2LMoSE" crossorigin="anonymous"/>
  <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.15.4/css/fontawesome.css" integrity="sha384-jLKHWM3JRmfMU0A5x5AkjWkw/EYfGUAGagvnfryNV3F9VqM98XiIH7VBGVoxVSc7" crossorigin="anonymous"/>

Which would would translate to this PHP code for your functions.php:

fa_custom_setup_cdn_webfont(
  'https://use.fontawesome.com/releases/v5.15.4/css/solid.css',
  'sha384-Tv5i09RULyHKMwX0E8wJUqSOaXlyu3SQxORObAI08iUwIalMmN5L6AvlPX2LMoSE'
);


fa_custom_setup_cdn_webfont(
  'https://use.fontawesome.com/releases/v5.15.4/css/fontawesome.css',
  'sha384-jLKHWM3JRmfMU0A5x5AkjWkw/EYfGUAGagvnfryNV3F9VqM98XiIH7VBGVoxVSc7'
);

Load the V4 Shims

You can also add version 4 compatibility with the v4 shims, if needed.

You should use the same version for the shims as you use for the main assets (such as either all.css, or some combination of fontawesome.css and styles like solid.css, as shown above).

Since all of our examples above use version 5.15.4, we’ll stick with that version in this example too. This PHP should be added to your functions.php in addition to the code you add to load the main Font Awesome assets.

fa_custom_setup_cdn_webfont(
  'https://use.fontawesome.com/releases/v5.15.4/css/v4-shims.css'
);

Setup Conflict Resolution

The most common problem we see when using WordPress, due to Font Awesome’s popularity, is where a WordPress site has a theme and any number of plugins, where each installs its own version of Font Awesome. Those end up conflicting with one another, producing confusing results.

Use our conflict detector to discover what those conflicts are on your site, and then use its results to tweak the following conflict resolution code below that you’ll add right into your functions.php.

Lay the Foundation

First we’ll lay a foundation with this function that you’ll call with a list of hashes representing the conflicts on your site as found by the conflict detector.

If you’re not a coder, don’t worry. Any code changes you’ll need to make will be limited to adjusting that list of hashes. You’ll probably never need to modify the code in this function.

/**
 * Font Awesome Conflict Resolution
 */
if (! function_exists('fa_custom_remove_conflicts') ) {
  function fa_custom_remove_conflicts($blacklist = array()) {
    foreach ( [ 'wp_print_styles', 'admin_print_styles', 'login_head' ] as $action ) {
      add_action(
        $action,
        function() use ( $blacklist ) {
          $collections = array(
            'style'  => wp_styles(),
            'script' => wp_scripts(),
          );


          foreach ( $collections as $key => $collection ) {
            foreach ( $collection->registered as $handle => $details ) {
              if ( FALSE !== array_search(md5($details->src), $blacklist) ) {
                $collection->dequeue([ $handle ]);
              } else {
                foreach ( [ 'before', 'after' ] as $position ) {
                  $data = $collection->get_data($handle, $position);
                  if( $data && is_array($data) &&
                    FALSE !== array_search(
                      md5("\n" . implode("\n", $data) . "\n"),
                      $blacklist)
                    ) {
                    unset( $collection->registered[$handle]->extra[$position] );
                  }
                }
              }
            }
          }
        },
        0
      );
    }
  }
}

Now, copy the following code into your functions.php, after the code above, adding an md5 hash to this “blacklist”, for each conflict that you want the above code above to remove for you.

We’ve got you started with two of them that really would conflict with Font Awesome 5 if they were present in your page, so you might as well leave them in the blacklist. In any case, hopefully it makes it more clear how you can add more as you see fit.

  • 7ca699f29404dcdb477ffe225710067f - This is the hash for the contents of the 4.7.0 font-awesome.css file.
  • 3c937b6d9b50371df1e78b5d70e11512 - This is the hash for the string: https://cdn.jsdelivr.net/npm/[email protected]/css/font-awesome.css. That’s a common CDN URL for loading Font Awesome 4.7.0.
fa_custom_remove_conflicts([
  '7ca699f29404dcdb477ffe225710067f',
  '3c937b6d9b50371df1e78b5d70e11512',
]);

Add Version 4 Compatibility

When the conflicts you remove include Font Awesome version 4, and your theme or plugins reference icons by names that changed between version 4 and version 5, you’ll need to do a little more work, adding the v4 shims. How you do that will depend on which way your trying to set up Font Awesome:

  • With a Kit: v4 compatibility is baked in (with some extra gourmet ingredients, not found in the other v4 compatibility recipes) So set up your kit in WordPress), and then in your kit settings, enable v4 compatibility. Super-easy. What are the extra gourmet ingredients, you ask? That’s another long story.
  • Without a Kit: follow the instructions for loading the v4 shims with SVG or Webfont, depending on which technology you’ve chosen to use.

Understand the Solution

Just what are these conflicting elements that you’re removing here?

They’re the <style>, <link>, or <script> elements that are being added to your pages by your theme or plugins, which load versions of Font Awesome other than the one you intend, and which will create chaos by doing so.

“But wait!” you say. “If I remove these, won’t it break my theme or those plugins that rely on them?”

Good question. Answer: probably not, usually not, but your mileage may vary.

Normally, a theme or plugin puts icons on the page, or enables you to do so, by adding <i> elements with approprate CSS classes.

The way Font Awesome version 4 used CSS classes is a little different from the way Font Awesome version 5 uses them. Where version 4 always used the fa class to indicate the underlying CSS attribute font-family: FontAwesome; for loading the Font Awesome webfont, version 5 introduced a couple of new ideas:

Multiple Styles

Corresponding to multiple CSS style “prefix” classes, replacing simply fa with one of fas (Solid), far (Regular), fal (Light), fab (Brands), fad (Duotone).

Any old uses of fa, the v4 way, are automatically understood in v5 as fas.

iconv4 codeEquivalent v5 code (Solid Style)
<i class="fa fa-user"></i><i class="fas fa-user"></i>

In version 5 (when you’re using the webfont technology—we’ll get to SVG next), each of these various style prefixes correspond to different webfonts!

The CSS rules handle all of that automatically for you: you just use the style prefix you want, and it loads the correct webfont files to display the icon in your chosen style.

SVG technology as an alternative to webfonts

In version 5, the style prefix on an <i> tag, doesn’t necessarily select a corresponding webfont.

If you’re using our SVG technology, there are no webfont files, but the same CSS style prefix tells our JavaScript code which style of icon to render as an SVG.

And let’s add a third variable, cause it’s more fun to juggle with three…

Icon Design Changes

Did you know that our icons designs may subtly change from version to version? Have a look at these changes in the user and users icons over time.

Changes in user and users icons over time

You can see the fa-user class never changes from version to version, but the image being rendered does change. Same for fa-users. And it’s not just changing from v4 to v5, but also changing from an earlier v5.0.4 to a later v5.0.12.

Alright, now with those factors in mind, here’s what’s (usually) happening to the icons being referenced by your theme and plugins when you use this conflict resolution technique to remove the versions of Font Awesome that they tried to install, and set up your own preferred version:

  • Anywhere there’s an icon referenced the v4 way, with fa, it’ll be automatically understood as fas.
  • Anywhere there’s an icon referenced in either the v4 or v5 way, it will be rendered using the version of Font Awesome you’ve set up, instead of the one your theme or plugin tried to set up.

Going back to that example of how the user icon has changed over time:

Suppose you have a plugin that tries to install its own Font Awesome version 4.7.0, and it uses <i class="fa fa-user"></i> (the v4 way) in its page templates, and then you setup Font Awesome version 5.10.0 with SVG.

Everywhere your plugin has <i class="fa fa-user"></i>, instead of getting a v4.7.0 webfont icon, you’ll get a Solid style (fas) SVG icon that looks like the user that was last changed in v5.0 12, as you see in the image above.

You will have effectively upgraded the icons being used by your theme and plugins.

When is this not how it works?

This is how it will work wherever this standard method of <i> tags with CSS class names are being used.

There are a few other less common ways of putting an icon on a page, like directly rendering SVG elements using JavaScript, such as our React component does. It’s less common to do it that, but also wouldn’t cause the same kind of conflicts for you, if one of your plugins happens to do it that way. It just means that this approach to conflict resolution won’t impact those cases in any way, so they’ll continue rendering the icons as they were originally intended by the plugin author.