Upgrading Guide

August 4, 2021 · View on GitHub

See the CHANGELOG.md for detailed information about what has changed between versions.

This guide is useful to figure out what you need to do between breaking changes.

As always, submit issues that you run into with this guide or with these upgrades to us.

5.15.3 to 5.15.4

The tripadvisor brand icon has been removed by legal request of Tripadvisor.

5.15.2 to 5.15.3

There are no breaking changes in this version upgrade.

5.15.1 to 5.15.2

There are no breaking changes in this version upgrade.

5.15.0 to 5.15.1

There are no breaking changes in this version upgrade.

5.14.0 to 5.15.0

The adobe icon has been removed by legal request of Adobe.

Font Awesome is no longer able to provide any logos or marks for the Adobe brand or their products.

In version 5.12.0 and 5.13.0 some of the icons were assigned unicode values that were outside the Private Unicode Area (PUA). This caused problems with some desktop software and caused the icons to show up as Chinese, Japanese, or Korean (CJK) ideographs.

The unicode values have been re-assigned to values within the PUA range.

If you were using any of the following icons with pseudo-elements you will need to change the CSS content value to the new unicode value.

Icon name	Old	New
bacteria	f959	e059
bacterium	f95a	e05a
box-tissue	f95b	e05b
caravan-alt	f900	e000
cat-space	f901	e001
coffee-pot	f902	e002
coffin-cross	f951	e051
comet	f903	e003
dailymotion	f952	e052
deezer	f977	e077
edge-legacy	f978	e078
fan-table	f904	e004
faucet	f905	e005
faucet-drip	f906	e006
firefox-browser	f907	e007
folder-download	f953	e053
folder-upload	f954	e054
galaxy	f908	e008
garage	f909	e009
garage-car	f90a	e00a
garage-open	f90b	e00b
google-pay	f979	e079
hand-holding-medical	f95c	e05c
hand-sparkles	f95d	e05d
hands-wash	f95e	e05e
handshake-alt-slash	f95f	e05f
handshake-slash	f960	e060
head-side-cough	f961	e061
head-side-cough-slash	f962	e062
head-side-mask	f963	e063
head-side-virus	f964	e064
heat	f90c	e00c
house	f90d	e00d
house-day	f90e	e00e
house-leave	f90f	e00f
house-night	f910	e010
house-return	f911	e011
house-signal	f912	e012
house-user	f965	e065
ideal	f913	e013
instagram-square	f955	e055
lamp-desk	f914	e014
lamp-floor	f915	e015
laptop-house	f966	e066
light-ceiling	f916	e016
light-switch	f917	e017
light-switch-off	f918	e018
light-switch-on	f919	e019
lungs-virus	f967	e067
microblog	f91a	e01a
microwave	f91b	e01b
mixer	f956	e056
outlet	f91c	e01c
oven	f91d	e01d
people-arrows	f968	e068
pied-piper-square	f91e	e01e
plane-slash	f969	e069
planet-moon	f91f	e01f
planet-ringed	f920	e020
police-box	f921	e021
portal-enter	f922	e022
portal-exit	f923	e023
pump-medical	f96a	e06a
pump-soap	f96b	e06b
radar	f924	e024
raygun	f925	e025
refrigerator	f926	e026
rocket-launch	f927	e027
rust	f97a	e07a
sensor	f928	e028
sensor-alert	f929	e029
sensor-fire	f92a	e02a
sensor-on	f92b	e02b
sensor-smoke	f92c	e02c
shield-virus	f96c	e06c
shopify	f957	e057
sink	f96d	e06d
siren	f92d	e02d
siren-on	f92e	e02e
soap	f96e	e06e
solar-system	f92f	e02f
sort-circle	f930	e030
sort-circle-down	f931	e031
sort-circle-up	f932	e032
space-station-moon	f933	e033
space-station-moon-alt	f934	e034
sprinkler	f935	e035
star-shooting	f936	e036
starfighter	f937	e037
starfighter-alt	f938	e038
starship	f939	e039
starship-freighter	f93a	e03a
stopwatch-20	f96f	e06f
store-alt-slash	f970	e070
store-slash	f971	e071
sword-laser	f93b	e03b
sword-laser-alt	f93c	e03c
swords-laser	f93d	e03d
telescope	f93e	e03e
temperature-down	f93f	e03f
temperature-up	f940	e040
tiktok	f97b	e07b
toilet-paper-slash	f972	e072
trailer	f941	e041
transporter	f942	e042
transporter-1	f943	e043
transporter-2	f944	e044
transporter-3	f945	e045
transporter-empty	f946	e046
ufo	f947	e047
ufo-beam	f948	e048
unity	f949	e049
unsplash	f97c	e07c
user-alien	f94a	e04a
user-robot	f94b	e04b
user-unlock	f958	e058
user-visor	f94c	e04c
users-slash	f973	e073
vacuum	f94d	e04d
vacuum-robot	f94e	e04e
virus	f974	e074
virus-slash	f975	e075
viruses	f976	e076
window-frame	f94f	e04f
window-frame-open	f950	e050

5.13.0 to 5.13.1

There are no breaking changes in this version upgrade.

5.12.1 to 5.13.0

There are no breaking changes in this version upgrade.

5.12.0 to 5.12.1

There are no breaking changes in this version upgrade.

5.11.2 to 5.12.0

The 9-pointed icon named "haykal" was renamed to "bahai" to better match the symbol. If you were previously using the misnamed icon rename to "bahai" when upgrading.

5.11.1 to 5.11.2

The scanner-image icon was previously using the same unicode value as the scanner icon.

This has now been fixed and the scanner-image icon has a unique unicode value.

The film-canister icon was misspelled as "film-cannister". This has been fixed.

5.11.0 to 5.11.1

There are no breaking changes in this version upgrade.

5.10.2 to 5.11.0

There are no breaking changes in this version upgrade.

5.10.1 to 5.10.2

There are no breaking changes in this version upgrade.

5.10.0 to 5.10.1

The Sass function fa-content-secondary which was part of the duotone.scss file has been removed due to its inconsistent behavior in different versions of Sass pre-processors. Specifically node-sass and sass didn't produce the same output.

5.9.0 to 5.10.0

The following icon shims have been changed to better match the original version 4 icon:

sort-alpha-desc
sort-amount-desc
sort-numeric-desc

5.8.2 to 5.9.0

The nintendo-switch icon has been removed by legal request of Nintendo of America Inc.

Font Awesome is no longer able to provide icons related to Nintendo, their gaming consoles, accessories, or games.

5.8.1 to 5.8.2

There are no breaking changes in this version upgrade.

5.8.0 to 5.8.1

There are no breaking changes in this version upgrade.

5.7.x to 5.8.0

Removing title elements from SVG sprites

Since the initial release of version 5, all the way back to 5.0.0 actually, we've included <title> elements in the SVG sprites.

In https://github.com/FortAwesome/Font-Awesome/issues/14595 a discussion outlines that this practice actually prevents normal efforts to make these sprites accessible according to web accessibility standards.

If you are using sprites please refer to our documentation on accessibility with Font Awesome.

Removing vertical-align from the .fa-icon Sass mixin

Font Awesome has supported Sass and Less CSS pre-processors for a long time.

The version 5 .fa-icon mixin which is present in scss/_mixins.scss previously included vertical-align which was incorrectly shifting icons.

If you have used this mixin in your own Sass files you will need to check the alignment of those icons after upgrading to 5.8.0.

5.7.1 to 5.7.2

There are no breaking changes in this version upgrade.

5.7.0 to 5.7.1

The cheeseburger icon incorrectly placed the cheese under the patty. This is unacceptable and we've fixed it.

5.6.x to 5.7.0

OTF and TTF files

The PostScript name has been changed from FontAwesome5ProSolid to FontAwesome5Pro-Solid. This was done to be more compatible with tooling such as XCode.

We've also update the Version specifier. Font files only support a MAJOR and MINOR version number so we have modifed our schema. For example, version 5.7.0 of Font Awesome is reflected as 329.472 in the individual font files.

Icon changes

The calendar-alt icon has been reverted back to the previous design in versions <= 5.6.0.

5.6.x to 5.6.3

The fire icon has been reverted back to the previous design in versions <= 5.5.0.

We have moved the redesigned icon to fire-alt.

5.6.0 to 5.6.1

There are no breaking changes in this version upgrade.

5.5.0 to 5.6.0

In this release we've taken time to re-organize the directory structure to prevent redundancy and improve findability.

Directory structure changes

Old path	New path
advanced-options/metadata	metadata
advanced-options/raw-svg	svgs
advanced-options/svg-sprites	sprites
advanced-options/use-with-node-js	js-packages
svg-with-js/js	js
svg-with-js/css	css
use-on-desktop	otfs
web-fonts-with-css/css	css
web-fonts-with-css/less	less
web-fonts-with-css/scss	scss
web-fonts-with-css/webfonts	webfonts

5.4.x to 5.5.0

There are no breaking changes in this version upgrade.

5.4.0 to 5.4.1

Categories were renamed from:

Holiday to Halloween
Seasonal to Autumn

The "wand" icon in version 5.4.0 matched the "wand-magic" icon. The magical sparkles have been removed for "wand". If you were relying on this decoration in your design switch to "wand-magic" to bring the magic back.

5.3.x to 5.4.0

There are no breaking changes in this version upgrade.

5.3.0 to 5.3.1

The following Pro-only icons were removed from Font Awesome Free as of 5.3.1:

abacus
calculator-alt
empty-set
function
integral
intersection
lambda
omega
pi
sigma
signal-alt
signal-alt-slash
signal-slash
square-root
tally
theta
tilde
union
value-absolute
volume
volume-down
volume-slash
wifi-slash

These icons were unintentionally included in 5.3.0.

5.x.x to 5.3.0

Sass mixin syntax has been updated to address a bug.

Use @extend %fa-icon to correctly maintain CSS order in output files.

~~Old way:~~

.twitter {
  @include fa-icon; /* incorrect */
  @extend .fab;

  &:before {
    content: fa-content($fa-var-twitter);
  }
}

New way:

.twitter {
  @extend %fa-icon; /* correct */
  @extend .fab;

  &:before {
    content: fa-content($fa-var-twitter);
  }
}

5.1.x to 5.2.x

There are no breaking changes in this version upgrade.

5.1.0 to 5.1.1

Less and Sass files incorrectly contained the "fa-" prefix for style files. These files have been renamed to be consistent with other files in the packages.

If you are using the Less or Sass file styles individually you will need to correct the names in your builds.

Old filename	New filename
less/fa-solid.less	less/solid.less
less/fa-regular.less	less/regular.less
less/fa-light.less	less/light.less
less/fa-brands.less	less/brands.less
scss/fa-solid.scss	scss/solid.scss
scss/fa-regular.scss	scss/regular.scss
scss/fa-light.scss	scss/light.scss
scss/fa-brands.scss	scss/brands.scss

5.0.x to 5.1.0

New packages available for browser-only integration

If you were previously using @fortawesome/fontawesome you need to switch to one of the new packages.

Our Free and Pro CDN provide access to JS, CSS, sprites, and separate SVG files.

We've now made these files conveniently available through NPM.

@fortawesome/fontawesome-free
@fortawesome/fontawesome-pro (private package, requires Pro subscription)

If you are familiar with the paths and options available with the CDN these packages should be familiar.

Information about Font Awesome Pro subscriptions can be found in your Font Awesome awesome account.

Renamed packages

The following packages have been renamed as part of 5.1.0 of Font Awesome.

All packages are in the @fortawesome NPM scope

Old package(1)	New package
fontawesome-free-webfonts	fontawesome-free
fontawesome-pro-webfonts	fontawesome-pro
fontawesome-free-solid	free-solid-svg-icons
fontawesome-free-regular	free-regular-svg-icons
fontawesome-free-brands	free-brands-svg-icons
fontawesome-pro-solid	pro-solid-svg-icons
fontawesome-pro-regular	pro-regular-svg-icons
fontawesome-pro-light	pro-light-svg-icons

(1) Old packages have now been deprecated. They are still available but will only receive high priority patch release fixes.

You'll need to update your package.json file with the renamed packages and new versions.

No more default imports

Recently we spent a good deal of time supporting TypeScript to enable us to create the Angular Font Awesome component. During that adventure we were convinced that we were going to remove default exports from all of our components, libraries, and packages. This is complete with the umbrella release of 5.1.0 of Font Awesome.

What does that mean?

~~Old way:~~

import fontawesome from '@fortawesome/fontawesome'
import solid from '@fortawesome/fontawesome-free-solid'
import faTwitter from '@fortawesome/fontawesome-free-brands/faTwitter'
import FontAwesomeIcon from '@fortawesome/vue-fontawesome'

library.add(solid, faTwitter)

New way:

import { library, dom } from '@fortawesome/fontawesome-svg-core'
import { fas } from '@fortawesome/free-solid-svg-icons'
import { faTwitter } from '@fortawesome/free-brands-svg-icons'
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'

library.add(fas, faTwitter)

// Kicks off the process of finding <i> tags and replacing with <svg>
dom.watch()

This is also a valid way to import icons that works if your tool does not support tree shaking:

import { faTwitter } from '@fortawesome/free-brands-svg-icons/faTwitter'

Improved support for tree shaking

Tree shaking is now functional by default and no additional configuration is required to make it work.

The shakable.es.js module has been removed and is no longer needed.

If you've previously configured tree shaking by modifying your webpack or rollup you can safely remove these.

We recommend that you check your bundle size after upgrading an ensure that file sizes are as you would expect.

module.exports = {
  // ...
  resolve: {
    alias: {
      '@fortawesome/fontawesome-free-solid$': '@fortawesome/fontawesome-free-solid/shakable.es.js'
    }
  }
}

const alias = require('rollup-plugin-alias')

rollup({
  // ...
  plugins: [
    alias({
      '@fortawesome/fontawesome-free-solid': 'node_modules/@fortawesome/fontawesome-free-solid/shakable.es.js'
    })
  ]
})

5.0.11 to 5.0.12

Due to a collision with the "r" glyph the R Project brand icon has been renamed to r-project.

5.0.x to 5.0.6

SVG Attribute was changed from data-fa-processed to data-fa-i2svg

As part of a bug fix for the release of 5.0.6 we renamed an attribute that was found on <svg> elements from data-fa-processed to data-fa-i2svg. We feel this more accurately reflects the intent and purpose.

This attribute is added to any icon that has been generated using fontawesome.dom.i2svg().

Be aware that data-fa-i2svg (or data-fa-processed) will no longer be present on icons that are created using fontawesome.icon().

If you've written and DOM queries that rely on data-fa-processed you should get things working again by doing a simple find and replace.