Are you using Font Awesome 4 on a project and ready to upgrade? Version 5 has been re-written and re-designed completely from scratch. We've tried to keep things as similar as possible to version 4, but there are a few differences to keep in mind when upgrading. Here's how to move to the latest and greatest.
Upgrading Quickly and Easily with Kits
Our Kits come with version 4 compatibility included - which manages the toughest parts of upgrading for you automatically. Create a kit, add its Kit embed code to your project, and we'll take care of the following:
Auto-mapping Old Icon Names
Kits' version 4 compatibility handles any references to older version icon names or aliases that have been changed.
Always Loading Your Kit's Version of Font Awesome
Your project may still have CSS that references the old font-family name, a common scenario when your project depends on other themes or plugins that load their own, older versions of Font Awesome. If we find any of those, we’ll override them to use the newer version of Font Awesome you’ve configured. This will also guarantee that any CSS pseudo-element rules you've set use the proper icon.
What's Changed From Version 4 to 5?
3 Different Icon Styles
We introduced a solid, regular, and light style of every icon in Font Awesome. We also separated out brand icons into their own style/category for easier use. We needed a way to reference a particular style when an icon is called in markup. It's still the case that for each icon you want to use, you need to 1) specify the icon's name and 2) use the proper prefix. Version 4 just had one prefix —
fa. Version 5 has four prefixes to let us set the style of any icon easily:
|New Prefix ||Icon Style ||SVG + JS Filename ||Web Font Filename ||Availability|
|Brands || |
|Solid || |
|Regular || |
|Light || |
|Duotone || |
Icon Name Changes
We removed aliases in version 5, each icon has one official name and some of those names have been adjusted under our new standard and conventions.
Outline Style Icons
Similarly, all icons that had an outlined style (and usually ended with
-o) now have a prefix of
far and have had their
-o suffix removed.
1. Remove Version 4 Assets & References**
Remove the files associated with Font Awesome Version 4 from your project - including the
fontawesome/ folder that contains web fonts (
fontawesome/fonts/), CSS (
fontawesome/css), and pre-processor options (
fontawesome/scss). If you’re using version 4's CDN(opens new window) , you can skip this step.
Next, remove references to version 4's CSS or JS from the
<head> of your templates/pages' HTML, including any references to version 4's CDN(opens new window) .
2. Set up Version 5 Assets & Add References
Check out our getting started details to walk through how to set up Font Awesome 5. You can use our Kits, download and host things yourself, or install Font Awesome through a package manager now.
3. Use Our Shim for More Support
Need some extra help and assurance that your existing icons will render without issue? We’ve created shim files to use as band-aids until you get the time to do a proper upgrade. Our v4 shims allow you to keep your old version 4 icon names, aliases, and syntax while mapping version 5 icons to your current references.
If you want to use them, you'll need to add an additional line to your Version 5 references. Here's an example using version 5's CDN:
The v4-shim is available to use in both our Web Fonts + CSS and SVG + JS Frameworks. If you're using our new and fancy SVG + JS way of rendering icons, just switch the
/css/all.css reference to
/js/all.js as well as
/js/v4-shims.js. Here's the example above switched to use our SVG + JS framework instead.
4. Update Styling
Update any custom styling you’ve added around Font Awesome icons (if applicable) including any rules you've set defining Unicode values that may have changed with CSS pseudo-elements.
5. Double Check Your Project's UI
Buy a friend a coffee and have them go through your project’s pages and views to make sure all icons are rendering as expected. Also, a staging or development version of your project is a great place to do this.
6. Update CSS Pseudo-element Rules
If you're using CSS pseudo-elements with version 4, upgrading to version 5 requires a fair amount of manual work. Below are the steps you'll need to follow:
- Update the font-family value - You'll want to make sure you change the
font-family to reference the new version of Font Awesome 5.
- Set a font-weight with each icon-based rule - You'll also need to set a
font-weight since version 5 has multiple styles mapped to different weights.
Icon Name Changes Between Version 4 and 5
Here's the list of all of the icons that have been renamed according to version 5's standards and conventions. Keep in mind you'll need to change all brand icons from version 4 to use the new
fab prefix instead of the old
Running into trouble? Check out our troubleshooting guide for answers to common questions about using Font Awesome on the web. All set? Then check out and enjoy all of the new icons added to version 5.