Upgrade Sass (SCSS)

We’ve worked hard to make the upgrading to Version 7 smooth and painless when using Sass, but there are a few steps and things to be mindful of.

Breaking Changes

We introduced some major changes that won’t break at a production or published project-level, but will break at the compilation step when switchingfrom Version 6 to Version 7’s Sass.

What Changed	Why We Changed It	What You Should Do
Sass Syntax converted to Dart Sass	LibSass is now deprecated. We wanted to be on tooling that is actively maintained and that the industry is building with	Confirm your project’s Sass compilation uses Dart Sass
Removed the fa- prefix from our _variables.scss variable names	We use @use to load partials now and recommend namespacing via our fa partial to reference them	Update any references to the old variable syntax to the new one accounting for namespacing (e.g. $fa-font-path -> fa.$font-path)
Removed the fa- prefix from our _mixins.scss mixin names	We use @use to load partials now and recommend namespacing via our fa partial to reference them	Update any references to the old mixin syntax to the new one accounting for namespacing (e.g. $fa-font-path -> fa.$font-path)
Removed the fa- prefix from our _functions.scss function names	We use @use to load partials now and recommend namespacing via our fa partial to reference them	Update any references to the old function syntax to the new one accounting for namespacing (e.g. $fa-font-path -> fa.$font-path)
Removed the fa-icon-* mixin	We provide an icon() mixin within each icon style partial loaded via @use that is more bullet-proof and efficient	Update any references to the old mixin to the new corresponding icon style mixin
Removed the fa-family-*mixin	We provide an icon() mixin within each icon style partial loaded via @use that is more bullet-proof and efficient	Update any references to the old mixin to the new corresponding icon style mixin
Renamed _fixed-width partial to _fa-widths	This better describes the options this file contians given the change to render all icons at a fixed width (of the full Icon Canvas) by default	Update any references to the old partial name to the new name in your SCSS compile
Removed sr-only and sr-only-focusable classes	These classes aren’t being used for our accessibility strategy anymore	Add a similar class to your own CSS if you want them
Separated bordered and pulled styling into separate partial files	We’ll be deprecating the Bordered Icons feature in a future release	Make sure your Sass compile includes both separate partials

Upgrading to Version 7’s Sass

If you’re using Font Awesome 6’s preprocessor assets, you’ll need to swap out and disconnect those old files, then place and new Version 7 files in your project. Next, you’ll need to update your project’s compilation as well as any references references to Font Awesome variables, mixins, and utilities. Follow the steps below to make these updates.

1. Remove Any Version 6 Files From Your Project

Locate the Font Awesome Version 6 Sass files in your project - these are most likely in the scss folder. Once found, remove those files to prevent the conflicts that may come from loading two different versions of Font Awesome in your Sass compile.

You’ll next want to remove Font Awesome Version 6’s Web Fonts from your project - these are most likely found in the webfonts folder you copied over when setting up v6.

2. Download Version 7’s Sass

Next, download Version 7 for the Web and unpack the files and icons. You can then follow some familiar steps to add Font Awesome 7 to your Sass.

3. Update Your Compile’s Syntax for Version 7

With the deprecation of Sass’s @import rule, Font Awesome’s files require a @use-based compilation. This is much different from how Version 6 was included in a project’s compilation.

We’ve made some utilities and documented how we recommend you structure your project’s compile with Font Awesome assets.

Here’s a complete example compile:

// customize variables
@use './fontawesome/variables' with (
  // customizing $font-path
  $font-path: "../webfonts",
);

// load Font Awesome core
@use './fontawesome/fontawesome';

// load Font Awesome helpers (mixins, functions, and variables) and make available via @forward
@use './fontawesome/fa' as fa;

// load individual Font Awesome styles
@use './fontawesome/solid.scss' as fa-solid;
@use './fontawesome/brands.scss' as fa-brands;

@use './fontawesome/duotone.scss' as fa-duotone;
@use './fontawesome/sharp-duotone.scss' as fa-sharp-duotone;

// Solid style of user
.user {
  @include fa-solid.icon(fa.$var-user);
}

// Bluesky brand icon
.bluesky {
  @include fa-brands.icon(fa.$var-bluesky);
}

// Duotone style of camera-retro
.camera-retro {
  @include fa-duotone.icon(fa.$var-paintbrush-fine);
}

// Sharp Solid style of trash
.trash {
   @include fa-sharp-duotone.icon(fa.$var-trash);
}

4. Update Existing Variable, Mixin, and Utility References

Since Version 7’s Sass/SCSS is built to be loaded using the @use rule, you’ll need to update any existing references to Font Awesome variables, mixins, and utilities.

The biggest change is that variable, mixin, and utility names are no longer namespaced via the fa-*. Instead, these are namespaced while using @use to load Font Awesome Sass/SCSS.

In the compile example above, variables, mixins, and utilities are namespaced with fa when you load the fontawesome/fa file…

// load  Font Awesome helpers (mixins, functions, and variables) and make available via @forward
@use './fontawesome/fa' as fa;

If you’ve written custom Sass/SCSS that leverages existing variables, mixins, or utilities. You’ll need to update to use the new V7 syntax as well.

Here’s an example of the before (V6) and after (V7):

/* V6 syntax */

/*
An example of old V6 Sass/SCSS for the Free Solid style of the arrow-right-to-bracket icon
.login {
  @include fa-icon-solid($fa-var-arrow-right-to-bracket);
}

An example of old V6 Sass/SCSS for a Sharp Thin style of user icon
.my-profile {
  @include fa-icon-thin($fa-var-user);
  @include fa-family-sharp();
}
*/

/* V7 syntax */
/* An example of updated V7 Sass/SCSS for a Solid style of arrow-right-to-bracket icon */
.login {
  @include fa-solid.icon(fa.$var-arrow-right-to-bracket);
}

/* An example of updated V7 Sass/SCSS for a Sharp Thin style of user icon */
.my-profile {
  @include fa-sharp-thin.icon(fa.$var-user);
}

Make sure you correctly import the styles you are using:

@use './fontawesome/solid' as fa-solid;
@use './fontawesome/sharp-thin' as fa-sharp-thin;

5. Check Your CSS Output and References

If you’re using the Font Awesome Sass compile to output your CSS directly, you may need to update your old Version 6 references to point to the new Version 7 assets you’ve compiled.

<head>
  <!-- link to your compiled css -->
  <link href="/your_path_to_version_7_compiled_files/css/fontawesome.css" rel="stylesheet" />
</head>
<body>
  <!-- Your icons should show up just as before. -->
</body>

---

You're all set!

Your project will now load Version 7 and render any existing icons using our newest and freshest icons and options. Are you running into trouble? Check out our troubleshooting guide for answers to common questions about using Font Awesome on the Web.