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.

Before You Get Started

In order to make use of these code snippets, you need to be able to check off all of these boxes:

• I have write access to my WordPress theme’s functions.php file.
• I know how to make changes to my theme’s functions.php file.
• I’m okay with making code changes to add Font Awesome into my WordPress files.

Set up a Kit

First we’ll lay a foundation with this function that you’ll call with your Kit embed code. 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 yourkitcode.js with your real Kit token, which you can find in your Kit settings.

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

---

Set up with the Font Awesome CDN

Font Awesome 6 Pro is not available on the Font Awesome CDN!

Font Awesome 6 is not available via the Font Awesome CDN. You can use a Kit or host Font Awesome 6 yourself to use v6 icons. If you’d still prefer to use the CDN, Font Awesome 5 still supports that.

---

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 “blocklist”, 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 6 if they were present in your page, so you might as well leave them in the blocklist. 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 6. Luckily for you, Version 4 compatibility is baked in to Kits! So set up your Kit in WordPress and you’re done.

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 and above use 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 and now Version 6 introduced a few new concepts:

Multiple Styles

Font Awesome 5 and above have multiple styles, and Version 6 is adds multiple families. These are defined by multiple CSS style “prefix” classes, replacing the simple fa with one of a variety of styles.

Any old uses of fa, the V4 way, are automatically understood in v5 and v6 as fa-solid.

icon	v4 code	Equivalent v5/v6 code (Solid Style)
	<i class="fa fa-user"></i>	<i class="fa-solid fa-user"></i>

In Version 6 (when you’re using the Web Font technology—we’ll get to SVG next), each of these various style prefixes correspond to different Web Fonts!

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

SVG technology as an alternative to Web Fonts

In Version 5, we added the ability to add icons as SVGs as well as the traditional Font Awesome Web Fonts. With Web Fonts, the style prefix on an <i> tag doesn’t necessarily select a corresponding Web Font. And if you’re using our SVG technology, there are no Web Font files, but the same CSS style prefix tells our JavaScript code which style of icon to render as an SVG.

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.

You can see the fa-user class never changes from version to version, but the image being rendered does change. Same for fa-users.

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 fa-solid.
• 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 6.0.0 with SVG.

Everywhere your plugin has <i class="fa fa-user"></i>, instead of getting a v4.7.0 Web Font icon, you’ll get a Solid style (fa-solid) SVG icon that looks like the user that was last changed in v6.0.0, 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 way, 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.