Font Awesome 7 vs Version 6: Breaking Changes and Migration Guide

Font Awesome 7 introduces multiple icon families with dedicated prefixes, restructured SCSS variables, and modernized JavaScript matchers while maintaining backward compatibility through fallback mechanisms.

Font Awesome 7 represents a significant architectural shift from version 6, transitioning from a monolithic prefix system to a multi-family architecture that supports duotone, sharp, and kit variants. According to the FortAwesome/Font-Awesome source code, this release restructures how CSS classes resolve to icon families and modernizes the JavaScript core for better performance.

Major Breaking Changes

Icon Families and Prefixes

Version 6 relied on a single "classic" family where prefixes like fa, fas, far, and fad all pointed to the same underlying set. In version 7, multiple families exist as distinct entities:

• Classic family: fas (solid), far (regular), fal (light), fat (thin)
• Duotone family: fad
• Sharp family: fass (solid), fasr (regular), fasl (light), fast (thin)
• Sharp-duotone family: fass-duotone
• Kit family: fak

The legacy fa alias now automatically rewrites to fas internally. In js-packages/@fortawesome/fontawesome-svg-core/index.js, the findIconDefinition function handles this translation (lines 15–22), ensuring that deprecated fa references resolve to the solid classic style.

CSS and SCSS Variable Restructuring

The SCSS architecture introduces new variable naming conventions in scss/_variables.scss (lines 4–6):

$css-prefix: fa !default;
$style: solid !default;  
$family: classic !default;

The old $style-family variable (line 55) is deprecated and scheduled for removal. Hundreds of new Unicode variables ($var-0, $var-a, etc.) enable more granular theming via CSS custom properties.

JavaScript API Modernization

The SVG core now prioritizes modern matchers for parsing duotone and multi-family icons, with legacy v6 matchers retained only as fallbacks. In js-packages/@fortawesome/fontawesome-svg-core/index.js around line 1545, the parsing logic prefers new family-specific matchers while maintaining backward compatibility for older SVG definitions.

Package Layout Changes

Version 7 abandons the monolithic fontawesome bundle in favor of granular packages:

• @fortawesome/fontawesome-svg-core: Core rendering engine
• @fortawesome/fontawesome-free: Free icon set (located at js-packages/@fortawesome/fontawesome-free)
• @fortawesome/fontawesome-pro: Pro icon set
• @fortawesome/fontawesome-kit: Custom kit integration

Step-by-Step Migration Guide

1. Update Package Dependencies

Replace v6 packages with v7 equivalents:

# npm / Yarn

npm install @fortawesome/fontawesome-free@7

# Or for Pro users:

npm install @fortawesome/fontawesome-pro@7

For CDN implementations, update the version string:

<!-- Version 7 CDN -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.0/css/all.min.css">

2. Adjust CSS and SCSS Imports

Update import paths to reflect the new package structure:

// Version 6 (old)
@import "~font-awesome/scss/fontawesome";

// Version 7 (new)
@import "~@fortawesome/fontawesome-free/scss/fontawesome";
@import "~@fortawesome/fontawesome-free/scss/solid";

If you previously overrode $fa-css-prefix, update to the new variable name $css-prefix (defined in scss/_variables.scss lines 4–6).

3. Update HTML Class Prefixes

Replace ambiguous references with explicit family prefixes:

<!-- Version 6 (still works but deprecated) -->
<i class="fa fa-solid fa-coffee"></i>

<!-- Version 7 (recommended) -->
<i class="fa-solid fa-coffee"></i>

For new families, use dedicated classes:

<i class="fa-duotone fa-clock"></i>
<i class="fa-sharp fa-solid fa-bolt"></i>
<i class="fa-kit fa-custom-icon"></i>

4. Migrate JavaScript Usage

Update icon lookup calls to use explicit prefixes:

// Version 6 (deprecated)
import { library, icon } from '@fortawesome/fontawesome-svg-core';
icon({ prefix: 'fa', iconName: 'coffee' });

// Version 7 (correct)
import { fas } from '@fortawesome/free-solid-svg-icons';
library.add(fas.faCoffee);

The core automatically rewrites fa to fas via internal mapping defined in PREFIX_TO_LONG_STYLE (lines 38–41 of js-packages/@fortawesome/fontawesome-svg-core/index.js).

5. Replace Deprecated SCSS Variables

Swap legacy variables for their v7 equivalents:

// Deprecated
$style-family: classic;

// Current
$family: classic;

6. Run Automated Upgrade Scripts

Font Awesome 7 includes a CLI tool for automated HTML refactoring:

npm run upgrade-web

This scanner rewrites class patterns in HTML files according to the new family architecture. Consult the official Web upgrade guide linked in UPGRADING.md for advanced configuration.

Practical Code Examples

HTML and CSS Implementation

<link rel="stylesheet" 
      href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.2.0/css/all.min.css">

<!-- Classic family solid style -->
<i class="fa-solid fa-user"></i>

<!-- Duotone family -->
<i class="fa-duotone fa-camera"></i>

<!-- Sharp family solid -->
<i class="fa-sharp fa-solid fa-star"></i>

SCSS Custom Prefix Configuration

// src/styles/icons.scss
@import "~@fortawesome/fontawesome-free/scss/fontawesome";
@import "~@fortawesome/fontawesome-free/scss/solid";

// Override default prefix
$css-prefix: myfa;

// Generated output uses: myfa-solid, myfa-user, etc.

<!-- Usage with custom prefix -->
<i class="myfa-solid myfa-coffee"></i>

JavaScript SVG Core Integration

import { library, dom } from '@fortawesome/fontawesome-svg-core';
import { fas } from '@fortawesome/free-solid-svg-icons';
import { fad } from '@fortawesome/free-duotone-svg-icons';
import { fak } from '@fortawesome/fontawesome-kit';

// Add classic solid icons
library.add(fas.faCoffee);

// Add duotone icons (new family support)
library.add(fad.faClock);

// Add custom kit icons
library.add(fak.faCustomIcon);

// Auto-replace <i> tags with SVG
dom.watch();

Handling Custom Configuration

If your application defines a custom CSS prefix via global configuration, maintain the existing setting:

window.FontAwesomeConfig = {
  cssPrefix: 'my-icon'
};

The library handles class name rewriting automatically through the config.cssPrefix logic in js-packages/@fortawesome/fontawesome-svg-core/index.js.

Key Source Files Reference

File	Purpose
README.md	High-level overview and versioning policy
UPGRADING.md	Official migration guides and documentation links
scss/_variables.scss	Core SCSS variables including $css-prefix and deprecated $style-family
js-packages/@fortawesome/fontawesome-svg-core/index.js	Core JavaScript API, prefix handling, and modern vs legacy SVG matchers
js-packages/@fortawesome/fontawesome-free/scss/fontawesome.scss	Entry point for free SCSS builds

Summary

• Font Awesome 6 is now Long-Term Support (LTS) receiving only critical bug fixes, while v7 is the active development branch
• Multiple icon families replace the monolithic classic system, requiring explicit prefixes (fas, fad, fass, fak) instead of the generic fa alias
• SCSS variables moved to a cleaner naming convention with $css-prefix and $family replacing legacy names
• JavaScript core prioritizes modern SVG matchers for v7 families while maintaining fallback support for v6 icon definitions
• Package structure shifted to granular npm packages under @fortawesome/ scope rather than the old monolithic bundle
• Automated migration tools via npm run upgrade-web streamline HTML class updates

Frequently Asked Questions

What happened to the generic fa prefix in Font Awesome 7?

The fa prefix still functions but now resolves internally to fas (classic solid). According to the source code in js-packages/@fortawesome/fontawesome-svg-core/index.js, the findIconDefinition method automatically rewrites fa references to fas for backward compatibility. However, explicit prefixes are recommended for clarity and future-proofing.

Do I need to change my existing SCSS variables when upgrading?

Only if you customized specific internal variables. The deprecated $style-family variable (line 55 in scss/_variables.scss) should be replaced with $family. The main $css-prefix variable (lines 4–6) functions identically to the old $fa-css-prefix but uses a new naming convention.

Will my Font Awesome 6 SVG files still work in version 7?

Yes. The JavaScript core in js-packages/@fortawesome/fontawesome-svg-core/index.js maintains legacy matchers as fallbacks (around line 1545) specifically for v6 SVG definitions. Modern matchers handle new duotone and sharp families for improved performance, but old files render correctly through the fallback mechanism.

How do I use the new Sharp or Kit families in my project?

Import the specific family packages and use their dedicated prefixes:

import { fass } from '@fortawesome/sharp-solid-svg-icons';
import { fak } from '@fortawesome/fontawesome-kit';

In HTML, use classes like fa-sharp fa-solid or fa-kit. These map to the fass and fak prefixes respectively, as defined in the PREFIX_TO_LONG_STYLE mapping within the core library.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}