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.
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
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.
Set up with the Font Awesome CDN
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
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.
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.
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?
<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:
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
|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
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
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
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
- 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.