# Font Awesome 7 vs Version 6: Breaking Changes and Migration Guide
> Explore Font Awesome 7 vs version 6 breaking changes. Learn how to migrate with our guide covering new icon families, SCSS variables, and JavaScript matchers. Upgrade today.
- Repository: [Font Awesome/Font-Awesome](https://github.com/FortAwesome/Font-Awesome)
- Tags: migration-guide
- Published: 2026-03-01
---
**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`](https://github.com/FortAwesome/Font-Awesome/blob/main/scss/_variables.scss) (lines 4–6):
```scss
$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:
```bash
# 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:
```html
```
### 2. Adjust CSS and SCSS Imports
Update import paths to reflect the new package structure:
```scss
// 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`](https://github.com/FortAwesome/Font-Awesome/blob/main/scss/_variables.scss) lines 4–6).
### 3. Update HTML Class Prefixes
Replace ambiguous references with explicit family prefixes:
```html
```
For new families, use dedicated classes:
```html
```
### 4. Migrate JavaScript Usage
Update icon lookup calls to use explicit prefixes:
```javascript
// 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:
```scss
// Deprecated
$style-family: classic;
// Current
$family: classic;
```
### 6. Run Automated Upgrade Scripts
Font Awesome 7 includes a CLI tool for automated HTML refactoring:
```bash
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`](https://github.com/FortAwesome/Font-Awesome/blob/main/UPGRADING.md) for advanced configuration.
## Practical Code Examples
### HTML and CSS Implementation
```html
```
### SCSS Custom Prefix Configuration
```scss
// 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.
```
```html
```
### JavaScript SVG Core Integration
```javascript
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 tags with SVG
dom.watch();
```
### Handling Custom Configuration
If your application defines a custom CSS prefix via global configuration, maintain the existing setting:
```javascript
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`](https://github.com/FortAwesome/Font-Awesome/blob/main/README.md) | High-level overview and versioning policy |
| [`UPGRADING.md`](https://github.com/FortAwesome/Font-Awesome/blob/main/UPGRADING.md) | Official migration guides and documentation links |
| [`scss/_variables.scss`](https://github.com/FortAwesome/Font-Awesome/blob/main/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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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:
```javascript
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.