Font Awesome 5 Official WordPress Plugin
- Description
- Installation
- For End Users
- For Developers
Loads Font Awesome 5 Free or Pro on your WordPress site. Provides features for developers of themes and other plugins to register their Font Awesome requirements with this plugin to ensure that a single, working version of Font Awesome is loaded that works across all WordPress components. Optionally, block some themes or plugins from trying to load their own versions of Font Awesome which might create conflicts and keep your icons from working correctly.
May be installed by WordPress site owners as a normal WordPress plugin, or shipped by developers as a composer dependency in their vendor bundles.
Supports both Free and Pro, optional use of version 4 compatibility (shims), pseudo-elements, and either the Webfont with CSS or SVG with Javascript method. The Start page on fontawesome.com describes the differences.
Loads Font Awesome from the official Font Awesome Free or Pro CDN.
To install directly as a WordPress plugin:
Follow installation instructions in the plugin directory.
For instructions on adding this as a composer package to install with your theme or plugin, see Install as Composer Dependency)
You can place an icon in a post, page, or widget using a shortcode:
[icon name="coffee"]
or straight HTML with an <i> tag:
<i class="fas fa-coffee"></i>Font Awesome 5 icon names and classes should be used.
When using HTML, you can access the full range of capabilities described on fontawesome.com.
When using shortcodes, the default style prefix is fas, Font Awesome Solid
You can specify a different style prefix like this:
[icon name="bell" prefix="far"]
The far prefix is for the Font Awesome Regular style.
Notice that in the shortcode, the name is just the Font Awesome 5 name of the icon, but when you use
the HTML <i> tag notation, you specify the icon in terms of its CSS class, which just means prepending the fa-.
So the name of the icon is bell, but the CSS class is fa-bell.
Many Font Awesome features are available simply by additional additional CSS classes:
- size
- fixed-width
- rotation
- animation
- border
- ...and more
You can add any of those classes through the shortcode like this:
[icon name="coffee" class="fa-2x fa-rotate-180"]
This makes the coffee icon bigger, and upside down.
For now, if you want to do even fancier things like...
...you'll need to use straight HTML, as shown in the documentation on fontawesome.com.
Suppose you have no themes or plugins activated that use this Font Awesome plugin. It's just you, looking to add icons to your WordPress site.
Simply install and activate the plugin. It will load sensible defaults for the latest version of Font Awesome 5 Free:
- Webfont with CSS method
- Version 4 compatibility (aka "v4shims")
Then just start adding Font Awesome HTML markup to your posts, pages, and templates. Refer to our documentation for basic usage, and for more fancy usage like Stacked Icons.
Look up available icons in our searchable Icon Gallery or Cheatsheet.
You can get to the plugin's options page in WordPress admin by clicking "Font Awesome" under the "Settings" menu, or clicking "Settings" on the plugin's entry in the list of plugins.
This options page won't be very complicated in this scenario, since no other WordPress components are using the plugin. Therefore, you could change the version and features settings on the options page to your heart's content without creating any conflicts with other components' requirements.
Consider a few configuration scenarios...
Again, suppose there are no other components (plugins or theme) that depend upon this plugin to load Font Awesome. It's just you, the web site owner, and you want to use SVG icons, and maybe some of the fancier features that come with them.
In the plugin's options page, on the "Method" dropdown menu, select "svg" instead of "webfont". Save those changes. That's it!
Now, your icons will render as SVG. You won't need to change any of the HTML markup (like the <i> tags you might have
already used under the webfont method).
You now can use some of the fancier features, like Layering, Text, and Counters.
Suppose you've purchased Font Awesome Pro. To enable those Pro icons on your web site, it's just two steps:
-
Login to your fontawesome.com account and go to the Services page. Add any web domains where you'll use the icons. This is a "white list". It tells our server that if the icons are being loaded from any of these web sites, it's OK to load them as long as your account is active.
-
Go to the plugin settings page and click the checkbox next to "Pro". Save that change.
That's it! Add Pro icons anywhere on your site.
Suppose you've installed a theme called "Radiance" and a plugin called "Shuffle" and that each of them depend on this plugin for their icons.
You don't need to do anything to configure them to work together. Rather, they use this plugin's API behind the scenes to register their own requirements, like whether they require a specific version of Font Awesome, or particular feature, like pseudo-elements.
On the plugin's options page, you can see in the "Client Requirements" section what Font Awesome requirements Radiance and Shuffle have. If they have conflicting requirements, you'll see a simple error message to help you diagnose and resolve the problem.
For example, suppose Radiance says it requires Font Awesome version 5.1.0 or later, but Shuffle says it requires version 5.0.13. Well, we can't satisfy both, and we can't just load both versions--one for each of them--because that could cause strange behavior, like breaking some or all of your icons. You can only load one version of Font Awesome at a time.
Instead, you'll see an error message that clearly shows which requirement is causing a conflict. You might resolve the problem by doing any or all of the following:
- Deactivate the Shuffle plugin
- Choose a different theme
- Contact the developers of Radiance or Shuffle to suggest that they change their requirements to reduce conflicts
While that might be a little bit of a hassle, at least it's clear and obvious and you know who to go to to resolve the problem. Not like the lawless days when every plugin and theme tried to load its own version of Font Awesome and everyone crossed their fingers hoping it just worked, and when it didn't, weren't sure why.
Now suppose that Radiance and Shuffle have compatible requirements, and that they make no particular requirement about the method---that is, they're content with either webfont or svg. Well, then, if you as the web site owner prefer to use SVG, just make that selection and save those changes. Your SVG requirement will satisfy Radiance, Shuffle, and your own preference. Anywhere that you or those components place icons, they'll be rendered as SVG.
Check the box next to "Remove Unregistered Clients" to try to stop other plugins or themes from loading unregistered (and therefore conflicting) versions of Font Awesome.
There are lots of themes and plugins out there that use Font Awesome. Normally, they load their own version. This works fine if they are the only component that uses Font Awesome, or if it just happens to be the case their version is the same as the version loaded by other plugins you may have installed (but even then, your web site could end up loading multiple instances of the same version, which is unnecessary, and bad for your web site's performance.)
Perhaps, one day, any plugin you'd want to use that depends on Font Awesome will be compatible with this plugin. All your icon version compatibility problems would disappear. In the meantime, we can attempt to stop those other themes or plugins from trying to load their own versions of Font Awesome, while still allowing them to display their icons as expected. Since there are lots of ways to load Font Awesome, there's no guarantee that our approach will work for discovering and stopping unregistered clients from loading their own versions. But we can try, and most of the time, we expect it to succeed.
Developers and ship this plugin as a dependency of their own plugins or themes. The advantage of doing so is to simplify the installation of your component for your users. Those users do not need to separately install the Font Awesome plugin.
The plugin uses the Singleton pattern to ensure that only one instance is loaded at any given time. So multiple themes and plugins that each ship the Font Awesome plugin as their own composer dependency can be activated together and still only one instance of the Font Awesome plugin will be loaded. They'll all use that one.
An advantage of this approach is that you can be sure that the Font Awesome plugin will be there when your code needs it, without creating conflicts with other plugins and themes, and you can avoid asking your users to install the Font Awesome plugin separately.
One caveat with this approach is that it's possible that the version of the Font Awesome plugin that is active when your code runs may not be the version you included in your composer bundle. It may be the version included in some other plugin's bundle, which happens to load before yours and takes the Singleton slot.
One way to handle this is to use FontAwesome::PLUGIN_VERSION, satisfies() and satisfies_or_warn() methods to react appropriately to unmet
plugin version requirements.
Unfortunately, there's no way to guarantee exactly what will be loaded at runtime: such is the nature of WordPress's pluggable nature. The best we can do is to try and provide an API that gives both developers and site owners more control and transparency into what's going on so that diagnosis and fixing of conflicts can be handled more straightforwardly. And hopefully, this plugin helps those conflicts to occur far less often in the first place.
In this version, all loading happens via the official Font Awesome Free CDN (use.fontawesome.com) or
Pro CDN (pro.fontawesome.com). No icon assets are bundled with this plugin.
So the end result of this plugin's work is the enqueuing of a stylesheet or script, resulting in the appropriate
<link> or <script> tag in the <head>.
Once a particular version and method is resolved, we load the all.js or all.css for that version, either
Free or Pro. This is the simplest, but normally not the most efficient. It would be more efficient
to load only the icon styles that the web site actually uses. Or it could potentially be made even more efficient
with some additional subsetting functionality. For this initial prototype version, though, we're not
focusing on optimizing efficiency, but on the basic loading and version settlement paradigm across various clients.
If this direction seems good, it would make sense to at least allow particular styles to be loaded.
We have made a REST API endpoint available on fontawesome.com which this plugin uses to retrieve up-to-date metadata about available releases.
This plugin computes a load specification, which is the set of version and configuration options that satisfy the requirements of all registered clients, including the WordPress site owner via the options page and any themes or plugins that depend on this Font Awesome plugin.
To compute that requires retrieving the latest metadata about Font Awesome releases from a REST API on fontawesome.com and reducing all of the requirements registered by all clients of this Font Awesome plugin.
We don't need to do all of that work on every page load. Once a load specification is computed, it will not change until the web site owner changes options on the options page. When this plugin computes a successful load specification, it stores it under an options key in the WordPress database and then re-uses that load specification for each page load. In that case, it will not fetch metadata from fontawesome.com nor process the requirements from registered clients.
You have two options:
- Peer Dependency
You would instruct your users to install this Font Awesome plugin separately when they install yours.
Your code would expect this plugin to be installed and active. It would register its requirements, receive
the action hook indicating successful load and confirmation of the final load specification. To place icons
in your templates, use <i> tags like normal.
- Composer Dependency
In your composer project directory:
composer require fortawesome/wordpress-fontawesome
In your plugin code, just require the plugin's entrypoint module, such as this:
require_once trailingslashit(__DIR__) . 'vendor/fortawesome/wordpress-fontawesome/font-awesome.php';Then you can access the FontAwesome class for class constants like FontAwesome::PLUGIN_VERSION, or
get an instance of the plugin with fa().
In any case, you would not ship any Font Awesome assets (no web font, CSS, JavaScript, or SVG files). Rather, you'd rely on this plugin to load the correct assets from the appropriate CDN with the appropriate configuration.
In the case of Font Awesome Pro, it would be a violation of the license terms to ship Pro assets, so that's a no-go no matter what. In the case of Font Awesome Free, while the license would support redistribution of those assets in your plugin or theme, doing so would defeat one of the chief goals of this plugin: to create a conflict-free experience of loading Font Awesome, both for developers and site owners. If you ship and load your own Font Awesome assets, you might just end up being the bad citizen whose code breaks other components.
Remember there are two different versions that you care about:
-
The version of Font Awesome itself: the assets that this plugin is trying to load correctly into WordPress pages.
-
The version of this plugin.
When the API of the plugin changes and your code expects a different version of this plugin than is active
at the time your code tries to use it, it could cause your code to break. So rather than assuming that the plugin
version active at runtime is the same as the version you were expecting, you can detect the version and react
appropriately. If your code needs to work in some alternate way, including maybe refusing to activate, you can
use satisfies_or_warn() to alert the site owner in the admin dashboard.
Rather than you supplying the Pro icons, it's your customer who enables Pro icons by setting up their Pro accounts and configuring this Font Awesome plugin to indicate that Pro is enabled. Your code can then respond to the presence of Pro and use Pro icons.
If you insist on having Pro icons available at runtime, you'd need to insist that your customers purchase a Font Awesome Pro license, install this plugin, and enable their Pro account for use with it.
In the event that the customer has not enabled Pro, your code would have to use only Free icons. Any Pro icons would fail to load correctly. This may mean designing your code to work with Free icons as a baseline, and then using Pro icons only when available.
Give us feedback about this to help us get the story right. For example, do you need to have a way to
require Pro (like v4shim can be required) so that you can count on it being there at runtime,
instead of designing for both alternatives, Free and Pro?
There are several clients in this GitHub repo that demonstrate how your code can use this plugin:
| Component | Description |
|---|---|
integrations/themes/theme-alpha |
Theme accepts default requirements, but also reacts to the presence of Pro by using Pro icons in a template. |
integrations/plugins/plugin-beta |
Plugin requires v4shim and a specific version. Uses some version 4 icon names. |
integrations/plugins/plugin-sigma |
Registered Client embedding Font Awesome as a composer dependency. When this plugin is activated, Font Awesome is implicitly activated, whether or not the Font Awesome plugin is directly installed or activated. |
See DEVELOPMENT.md for instructions on how you can run a dockerized WordPress environment and experiment with these examples.