Font Awesome 7.2.0 Free is a distribution-only icon framework delivering ~2,000+ solid icons, ~270+ regular icons, and ~580+ brand icons through two rendering approaches: CSS + Web Fonts and SVG + JavaScript. This guide covers the internal architecture, configuration surface, deployment strategies, and every integration point an administrator or developer needs to operate Font Awesome at scale.
1. Architecture Overview
1.1 Distribution Model
Font Awesome 7 Free ships as a pre-built distribution package. There is no build-from-source workflow, no compilation step, and no build toolchain to maintain. The repository (23,058 files, 5.3M source characters) contains every deliverable format ready for deployment.
The distribution breaks into ten distinct asset categories, each serving a different integration pattern:
| Asset Directory | Contents | Use Case |
|---|---|---|
css/ + webfonts/ |
Stylesheets + WOFF2/TTF font files | Traditional CSS integration |
js/ |
JavaScript modules + icon data | SVG rendering pipeline |
scss/ |
SCSS partials + entry points | Build-system CSS customization |
svgs/ |
Individual SVG files (cropped viewBox) | Direct SVG embedding |
svgs-full/ |
Individual SVGs (640x640 viewBox) | Uniform-dimension embedding |
sprites/ + sprites-full/ |
SVG sprite sheets | <use> reference pattern |
svg-objects/ + svg-full-objects/ |
JSON icon definitions | Programmatic icon access |
otfs/ |
OpenType font files | Desktop / print usage |
metadata/ |
YAML/JSON icon + category data | Tooling and search integration |
js-packages/@fortawesome/ |
Scoped NPM packages | Tree-shakeable JS imports |
1.2 Dual Rendering Architecture
Font Awesome supports two fundamentally different rendering pipelines. They are mutually exclusive in most deployments.
CSS + Web Fonts renders icons as font glyphs. The browser loads WOFF2 font files and maps CSS classes to Unicode code points. This approach requires no JavaScript, produces no DOM mutations, and works in environments where script execution is restricted.
SVG + JavaScript replaces <i> elements with inline <svg> elements at runtime. The SVG Core engine traverses the DOM, matches elements by CSS class, looks up icon definitions in its library, and injects SVG markup. This approach enables layering, masking, transforms, power transforms, and per-icon styling that the font approach cannot achieve.
Important
Do not load both
all.css(Web Fonts) andall.js(SVG+JS) on the same page. The SVG+JS engine will attempt to replace icons that the CSS approach already rendered, producing duplicated or broken output. Choose one rendering pipeline per page.
1.3 SVG Core Engine
The SVG Core engine (fontawesome-svg-core) is a ~4,000-line runtime that handles:
- Icon library management —
library.add()registers icon definitions;library.reset()clears them - DOM traversal — scans for elements matching the configured
cssPrefix(default:fa) <i>to<svg>replacement — transforms icon placeholder elements into inline SVG- MutationObserver — watches for dynamically added content and auto-replaces new icons
- CSS injection — automatically injects required styles into
<head> - Pseudo-element scanning — optionally scans
::beforeand::afterpseudo-elements for icon content - SVG rendering — generates SVG with transforms, masks, layers, counters, and text overlays
- Conflict detection — identifies multiple Font Awesome versions on the same page
- Performance measurement — optional timing instrumentation via
performance.mark()
The engine operates in two modes controlled by config.mutateApproach:
'async'(default) — usesrequestAnimationFramefor DOM mutations, preventing layout thrashing'sync'— performs mutations immediately, useful for server-side rendering or testing
1.4 Icon Family and Prefix System
Font Awesome 7 organizes icons into families and styles. Each combination maps to a short prefix used in CSS classes and JavaScript lookups.
Free edition families:
| Font Family Name | Weight | Prefix | CSS Class |
|---|---|---|---|
| Font Awesome 7 Free | 900 | fas |
fa-solid |
| Font Awesome 7 Free | 400 | far |
fa-regular |
| Font Awesome 7 Brands | 400 / normal | fab |
fa-brands |
Classic family prefix mapping (Free):
classic: { brands: "fab", regular: "far", solid: "fas" }
Pro families (architecturally present in the codebase but not usable in Free):
| Font Family | Weights and Prefixes |
|---|---|
| Font Awesome 7 Pro | 900: fas, 400: far, 300: fal, 100: fat |
| Font Awesome 7 Duotone | 900: fad, 400: fadr, 300: fadl, 100: fadt |
| Font Awesome 7 Sharp | 900: fass, 400: fasr, 300: fasl, 100: fast |
| Font Awesome 7 Sharp Duotone | 900: fasds, 400: fasdr, 300: fasdl, 100: fasdt |
Additional Pro families include Jelly, Jelly Fill, Jelly Duo, Slab, Slab Press, Thumbprint, Notdog, Notdog Duo, Etch, Graphite, Chisel, Whiteboard, Utility, Utility Duo, and Utility Fill (19 families total across the full architecture).
All valid short prefixes in the codebase:
fa, fas, far, fal, fat, fad, fadr, fadl, fadt, fab, fass, fasr, fasl, fast,
fasds, fasdr, fasdl, fasdt, faslr, faslpr, fawsb, fatl, fans, fands, faes,
fagt, fajr, fajfr, fajdr, facr, fausb, faudsb, faufsb
Note
In the Free edition, only
fas,far, andfabresolve to actual icon data. The remaining prefixes exist in the engine's lookup tables for Pro compatibility but will produce missing-icon warnings if used without Pro icon packs.
2. System Requirements
2.1 Runtime Requirements
Browser support (CSS + Web Fonts): Any browser supporting WOFF2 web fonts (all modern browsers, IE 11+ with TTF fallback).
Browser support (SVG + JS): Any browser supporting inline SVG and MutationObserver. IE 11 requires polyfills for Symbol, Array.from, and Object.assign.
Node.js (NPM packages): >= 6.0.0
2.2 Package Sizes
| Asset | File | Approx. Size |
|---|---|---|
| Web Font (Solid) | fa-solid-900.woff2 |
~150 KB |
| Web Font (Regular) | fa-regular-400.woff2 |
~25 KB |
| Web Font (Brands) | fa-brands-400.woff2 |
~110 KB |
| CSS (all, minified) | all.min.css |
~90 KB |
| JS (all, minified) | all.min.js |
~500 KB |
| JS (core only, minified) | fontawesome.min.js |
~70 KB |
2.3 NPM Package Inventory
The js-packages/@fortawesome/ directory contains scoped packages for tree-shaking workflows:
| Package | Files | Purpose |
|---|---|---|
fontawesome-free |
All-in-one | CSS, JS, SVGs, sprites, webfonts, SCSS, metadata |
fontawesome-svg-core |
Core engine | SVG rendering, config, library, DOM, layers |
fontawesome-common-types |
TypeScript | Type definitions for all icon interfaces |
free-solid-svg-icons |
3,991 files | Individual solid icon exports |
free-regular-svg-icons |
548 files | Individual regular icon exports |
free-brands-svg-icons |
1,175 files | Individual brand icon exports |
3. Configuration Reference
3.1 SVG Core Configuration Object
The SVG Core engine exposes a mutable config object. All properties can be set before or after initialization. Changes to config after dom.watch() has started take effect on the next DOM scan cycle.
| Key | Type | Default | Description |
|---|---|---|---|
cssPrefix |
string |
'fa' |
CSS class prefix for icon detection. Elements must have this prefix class to be recognized. |
styleDefault |
string |
'solid' |
Default icon style when none is specified. |
familyDefault |
string |
'classic' |
Default icon family. |
replacementClass |
string |
'svg-inline--fa' |
CSS class added to generated <svg> elements. |
autoReplaceSvg |
boolean |
true |
Whether to automatically replace <i> tags with <svg>. Set to false for manual control via dom.i2svg(). |
autoAddCss |
boolean |
true |
Whether to inject Font Awesome CSS into <head> automatically. |
searchPseudoElements |
boolean |
false |
Whether to scan CSS ::before / ::after pseudo-elements for icon content. |
searchPseudoElementsWarnings |
boolean |
true |
Whether to log warnings when pseudo-element scanning encounters issues. |
searchPseudoElementsFullScan |
boolean |
false |
Whether to perform a full DOM scan for pseudo-elements (expensive). |
observeMutations |
boolean |
true |
Whether to use MutationObserver for dynamic content. |
mutateApproach |
string |
'async' |
DOM mutation strategy: 'async' (requestAnimationFrame) or 'sync' (immediate). |
keepOriginalSource |
boolean |
true |
Whether to preserve the original <i> element as a comment node. |
measurePerformance |
boolean |
false |
Whether to emit performance.mark() / performance.measure() timing data. |
showMissingIcons |
boolean |
true |
Whether to render a visible placeholder when an icon definition is not found. |
Tip
For server-side rendering (SSR) scenarios, set
mutateApproach: 'sync',observeMutations: false, andautoAddCss: false. Inject the CSS manually in your server-rendered HTML<head>.
3.2 Setting Configuration
Before loading (SVG+JS global script):
<script>
window.FontAwesomeConfig = {
searchPseudoElements: true,
observeMutations: false
};
</script>
<script src="/js/all.min.js"></script>
After loading (SVG Core API):
import { config } from '@fortawesome/fontawesome-svg-core';
config.autoReplaceSvg = false;
config.searchPseudoElements = true;
config.measurePerformance = true;
3.3 Build-time Configuration (Babel Macro)
The import macro system uses babel-plugin-macros configuration. Add to babel-plugin-macros.config.js or the babelMacros key in package.json:
// babel-plugin-macros.config.js
module.exports = {
'fontawesome-svg-core': {
license: 'free' // 'free' or 'pro'
}
};
3.4 Environment Variable
The conflict detection module (conflict-detection.js) reads one environment variable:
| Variable | Used In | Purpose |
|---|---|---|
NODE_ENV |
conflict-detection.js |
Controls whether conflict detection runs (may be skipped in production builds) |
4. Deployment & Scaling
4.1 CDN Deployment
The simplest deployment uses a public CDN. No self-hosted infrastructure required.
CSS + Web Fonts via CDN:
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.2.0/css/all.min.css"
integrity="sha384-..." crossorigin="anonymous">
SVG + JS via CDN:
<script src="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.2.0/js/all.min.js"
integrity="sha384-..." crossorigin="anonymous"></script>
Warning
CDN availability issues have been reported. GitHub issue #21526 documents
npm.fontawesome.comreturning 404 errors due to a Cloudsmith redirect change. Issue #21527 reports 301 redirects tocloudsmith.iocausing installation failures. For mission-critical deployments, self-host the assets.
4.2 Self-Hosted Deployment
Copy the required asset directories to your web server's static file root.
Minimal CSS + Web Fonts deployment:
/static/
css/
all.min.css (or selective: fontawesome.min.css + solid.min.css)
webfonts/
fa-solid-900.woff2
fa-solid-900.ttf
fa-regular-400.woff2
fa-regular-400.ttf
fa-brands-400.woff2
fa-brands-400.ttf
The CSS files reference webfonts via relative paths (../webfonts/). If your directory structure differs, override the $fa-font-path SCSS variable or modify the CSS @font-face src URLs.
SCSS customization for custom font paths:
$fa-font-path: '/assets/fonts/fontawesome';
@import 'fontawesome';
@import 'solid';
Minimal SVG + JS deployment:
/static/
js/
all.min.js (or selective: fontawesome.min.js + solid.min.js)
4.3 NPM / Bundler Deployment
Install via NPM for tree-shaking support:
npm install @fortawesome/fontawesome-svg-core
npm install @fortawesome/free-solid-svg-icons
npm install @fortawesome/free-regular-svg-icons
npm install @fortawesome/free-brands-svg-icons
Tree-shaking individual icons:
import { library, dom } from '@fortawesome/fontawesome-svg-core';
import { faUser, faHome } from '@fortawesome/free-solid-svg-icons';
library.add(faUser, faHome);
dom.watch();
This imports only the two icons, not the entire 3,991-icon solid pack. Webpack, Rollup, and other bundlers with tree-shaking will eliminate unused icon exports.
Tip
Tree shaking with Webpack 5 requires
sideEffects: falsein your bundler config for the icon packages. See GitHub issue #18020 for known edge cases.
4.4 Selective Loading (CSS Approach)
Instead of loading all.min.css (which includes every style), load only what you need:
<!-- Core (required) -->
<link rel="stylesheet" href="/css/fontawesome.min.css">
<!-- Only the styles you use -->
<link rel="stylesheet" href="/css/solid.min.css">
<link rel="stylesheet" href="/css/brands.min.css">
<!-- Skip regular.min.css if you don't use fa-regular icons -->
4.5 Selective Loading (JS Approach)
<!-- Core (required) -->
<script src="/js/fontawesome.min.js"></script>
<!-- Only the packs you use -->
<script src="/js/solid.min.js"></script>
<!-- Skip brands.min.js and regular.min.js if unused -->
4.6 SVG Sprites Deployment
SVG sprites offer a middle ground: no JavaScript, no font loading, but requires <use> references.
<svg class="fa-solid fa-user" role="img" aria-label="User">
<use href="/sprites/solid.svg#user"></use>
</svg>
Two sprite variants exist:
| Directory | ViewBox | Use Case |
|---|---|---|
sprites/ |
Cropped per icon | Tighter bounding boxes, natural sizing |
sprites-full/ |
640x640 uniform | Consistent dimensions across all icons |
4.7 HTTP Headers for Self-Hosted Assets
Configure your web server for optimal font delivery:
# WOFF2 fonts - immutable, long cache
location ~* \.woff2$ {
add_header Cache-Control "public, max-age=31536000, immutable";
add_header Access-Control-Allow-Origin "*";
}
# CSS/JS - versioned, long cache
location ~* \.(css|js)$ {
add_header Cache-Control "public, max-age=31536000, immutable";
}
Important
WOFF2 fonts require correct CORS headers when served from a different origin than the HTML document. Without
Access-Control-Allow-Origin, browsers will silently fail to load the fonts with no visible error in the page (icons appear as empty squares).
5. Operations
5.1 CSS Files Inventory
All CSS files exist in both standard and minified variants:
| File | Purpose |
|---|---|
all.css |
Everything: core + solid + regular + brands |
fontawesome.css |
Core framework only (no icons) |
solid.css |
Solid style definitions |
regular.css |
Regular style definitions |
brands.css |
Brand icon definitions |
svg-with-js.css |
Styles for SVG+JS rendering mode |
svg.css |
SVG-specific styles |
v4-font-face.css |
Font-face declarations mapping v4 font names |
v4-shims.css |
v4 class name compatibility |
v5-font-face.css |
Font-face declarations mapping v5 font names |
5.2 JavaScript Files Inventory
| File | Purpose |
|---|---|
all.js |
Complete: core engine + all icon packs |
fontawesome.js |
Core engine only (no icons) |
solid.js |
Solid icon definitions |
regular.js |
Regular icon definitions |
brands.js |
Brand icon definitions |
conflict-detection.js |
Multi-version conflict scanner |
v4-shims.js |
v4 to v7 class name compatibility |
5.3 Webfont Files
| File | Style | Format |
|---|---|---|
fa-solid-900.woff2 |
Solid | WOFF2 (primary) |
fa-solid-900.ttf |
Solid | TrueType (fallback) |
fa-regular-400.woff2 |
Regular | WOFF2 |
fa-regular-400.ttf |
Regular | TrueType |
fa-brands-400.woff2 |
Brands | WOFF2 |
fa-brands-400.ttf |
Brands | TrueType |
5.4 SCSS Partials Reference
The SCSS source in scss/ provides customization points for build-system integrations:
| Partial | Purpose |
|---|---|
_variables.scss |
All SCSS variables ($fa-font-path, $fa-css-prefix, sizes, colors) |
_core.scss |
Base .fa class styles |
_icons.scss |
Icon unicode mappings |
_sizing.scss |
fa-2xs through fa-2xl and fa-1x through fa-10x |
_animated.scss |
fa-spin, fa-pulse, fa-beat, fa-fade, fa-bounce, fa-flip, fa-shake |
_bordered.scss |
fa-border styling |
_pulled.scss |
fa-pull-left, fa-pull-right, fa-pull-start, fa-pull-end |
_rotated-flipped.scss |
fa-rotate-*, fa-flip-* |
_stacked.scss |
fa-stack, fa-stack-1x, fa-stack-2x |
_list.scss |
fa-ul, fa-li |
_mixins.scss |
Reusable SCSS mixins |
_functions.scss |
SCSS helper functions |
_widths.scss |
fa-fw, fa-width-auto, fa-width-fixed |
_fa.scss |
Main import aggregator |
_shims.scss |
v4 compatibility class definitions |
Entry point files:
| File | Imports |
|---|---|
fontawesome.scss |
Core framework (no icon definitions) |
solid.scss |
Solid icon font-face + classes |
regular.scss |
Regular icon font-face + classes |
brands.scss |
Brands icon font-face + classes |
v4-shims.scss |
v4 compatibility layer |
5.5 Metadata Files
The metadata/ directory contains machine-readable icon data:
| File | Format | Contents |
|---|---|---|
icons.yml |
YAML | Complete icon definitions (names, unicode, styles, search terms) |
categories.yml |
YAML | Icon categorization (accessibility, alert, alphabet, animals, arrows, astronomy, automotive, buildings, business, camping, charity, etc.) |
icon-families.json |
JSON | Icon family and style metadata |
icon-families.yml |
YAML | Same data in YAML format |
shims.yml |
YAML | v4 to v7 icon name mappings |
sponsors.yml |
YAML | Sponsor attribution data |
5.6 Version Upgrade Checklist
When upgrading Font Awesome versions:
- Replace all asset files (
css/,js/,webfonts/, etc.) - Update CDN URLs if using CDN references
- Update
integrityhashes on all<link>and<script>tags - If using NPM:
npm update @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons(etc.) - Check
shims.ymlfor any removed icon name mappings - Test with
conflict-detection.jsto ensure no old versions remain - Verify SCSS variable overrides still compile against new partials
6. Performance
6.1 CSS + Web Fonts Performance
The Web Fonts approach has a well-understood performance profile:
- Initial load: One CSS file + one WOFF2 font per style used (typically 2-3 HTTP requests after the HTML)
- FOUT (Flash of Unstyled Text): Icons may appear as blank squares until the font loads. Use
font-display: swap(already set in the distributed CSS) to show fallback content during loading - Rendering: Zero JavaScript overhead; icons render as font glyphs with native browser text rendering
Optimization for large pages:
If using only solid icons, load fontawesome.min.css + solid.min.css instead of all.min.css. This avoids downloading regular and brand icon class definitions.
Note
GitHub issue #21461 reports slow loading times for
fa-solid-900.woff2. For latency-sensitive applications, preload the font:<link rel="preload" href="/webfonts/fa-solid-900.woff2" as="font" type="font/woff2" crossorigin>.
6.2 SVG + JS Performance
The SVG+JS approach has higher overhead but more capability:
- Initial load: JavaScript parsing + execution of icon definitions (~500 KB minified for
all.min.js) - DOM traversal: Full document scan on
DOMContentLoadedto find and replace icon elements - MutationObserver: Ongoing cost for watching DOM changes (disable with
observeMutations: falsefor static pages) - Pseudo-element scanning: Expensive when enabled.
searchPseudoElements: truetriggersgetComputedStyle()calls across the DOM.searchPseudoElementsFullScan: truemakes this even more expensive.
Performance measurement:
Enable timing instrumentation:
import { config } from '@fortawesome/fontawesome-svg-core';
config.measurePerformance = true;
This emits performance.mark() and performance.measure() entries visible in browser DevTools Performance tab.
6.3 Tree Shaking Impact
Loading all solid icons via all.min.js: ~500 KB minified.
Loading two icons via tree-shaking:
import { faUser, faHome } from '@fortawesome/free-solid-svg-icons';
// Bundled output: core (~70KB) + 2 icon definitions (~1KB)
Reduction: ~85% smaller JavaScript payload for typical applications using 10-50 icons.
6.4 Rendering Performance Tips
| Scenario | Recommendation |
|---|---|
| Static content, no dynamic icons | observeMutations: false, autoReplaceSvg: false, call dom.i2svg() once |
| SPA with route changes | Keep observeMutations: true (default) |
| Large icon-heavy pages (500+ icons) | Use CSS + Web Fonts instead of SVG + JS |
| Print stylesheets | Use CSS + Web Fonts; SVG+JS has known print issues (#20848) |
| SSR / Node.js rendering | Set mutateApproach: 'sync', disable DOM observation |
7. Security
7.1 Content Security Policy (CSP)
CSS + Web Fonts CSP requirements:
style-src 'self';
font-src 'self';
If using a CDN:
style-src 'self' https://cdnjs.cloudflare.com;
font-src 'self' https://cdnjs.cloudflare.com;
SVG + JS CSP requirements:
script-src 'self';
style-src 'self' 'unsafe-inline';
The SVG+JS engine injects CSS into <head> via dom.css() when autoAddCss: true. This requires 'unsafe-inline' in style-src. To avoid this:
config.autoAddCss = false;
// Manually include the CSS from dom.css() in your build pipeline
Caution
Setting
autoAddCss: true(the default) requiresstyle-src 'unsafe-inline'in your CSP policy. For applications with strict CSP requirements, disable auto-injection and bundle the CSS separately.
7.2 Subresource Integrity (SRI)
When loading from CDNs, always include integrity and crossorigin attributes:
<link rel="stylesheet" href="https://cdn.example.com/css/all.min.css"
integrity="sha384-HASH_HERE" crossorigin="anonymous">
Generate hashes from your local copy:
openssl dgst -sha384 -binary css/all.min.css | openssl base64 -A
7.3 Supply Chain Considerations
Font Awesome is distributed via:
- npmjs.com —
@fortawesome/fontawesome-free(public registry) - npm.fontawesome.com — Pro packages (private registry, requires auth token)
- CDN providers — cdnjs, jsDelivr, unpkg
The Free edition requires no authentication tokens, private registries, or license keys. All assets are MIT/OFL/CC-BY licensed and publicly available.
7.4 SVG Injection Security
The SVG+JS engine injects SVG markup into the DOM. The icon data (path definitions) comes from the icon packages themselves. Custom icon definitions added via library.add() should be validated to ensure SVG path data does not contain script injection payloads. The engine does not execute <script> elements within SVG, but malicious onload or event handler attributes in custom definitions could pose a risk in theory.
8. Developer Internals
8.1 Icon Definition Schema
Every icon in Font Awesome follows this schema (defined in schemas/icon-definition.schema.json):
{
"prefix": "fas",
"iconName": "star",
"icon": [
512,
512,
[],
"f005",
"M287.9..."
]
}
The icon array contains exactly five elements:
| Index | Type | Description |
|---|---|---|
| 0 | number |
SVG viewBox width |
| 1 | number |
SVG viewBox height |
| 2 | string[] |
Ligatures (deprecated, typically empty []) |
| 3 | string |
Unicode code point (hex) |
| 4 | string or string[] |
SVG path data. Single string for mono icons; two-element array [primary, secondary] for duotone |
The IconPathData type is string | string[] to accommodate both mono and duotone icons in the same schema.
8.2 TypeScript Type System
The fontawesome-common-types package defines the type vocabulary for the entire ecosystem:
type IconFamily = "classic" | "duotone" | "sharp" | "sharp-duotone" |
"chisel" | "etch" | "graphite" | "jelly" | "jelly-duo" | "jelly-fill" |
"notdog" | "notdog-duo" | "slab" | "slab-press" | "thumbprint" |
"utility" | "utility-duo" | "utility-fill" | "whiteboard";
type IconPrefix = "fas" | "fass" | "far" | "fasr" | "fal" | "fasl" |
"fat" | "fast" | "fad" | "fadr" | /* ... 34 values total */;
type CssStyleClass = "fa-solid" | "fa-regular" | "fa-light" | "fa-thin" |
"fa-duotone" | "fa-brands" | "fa-semibold";
type IconStyle = "solid" | "regular" | "light" | "thin" | "duotone" |
"brands" | "semibold";
type IconPathData = string | string[];
interface IconDefinition {
prefix: IconPrefix;
iconName: IconName;
icon: [
number, // width
number, // height
string[], // ligatures
string, // unicode
IconPathData // svgPathData
];
}
interface IconLookup {
prefix: IconPrefix;
iconName: IconName;
}
interface IconPack {
[key: string]: IconDefinition;
}
8.3 SVG Core API Reference
The @fortawesome/fontawesome-svg-core package exports these members:
dom object:
| Method | Signature | Description |
|---|---|---|
i2svg |
(params?: { node?: Node }) => Promise<void> |
Convert <i> elements to <svg> within a given node (or entire document) |
css |
() => string |
Return the CSS string that Font Awesome needs |
insertCss |
() => void |
Inject CSS into the document <head> |
watch |
() => void |
Start MutationObserver + initial i2svg() |
library object:
| Method | Signature | Description |
|---|---|---|
add |
(...definitions: (IconDefinition | IconPack)[]) => void |
Register icons for lookup |
reset |
() => void |
Clear all registered icons |
parse object:
| Method | Signature | Description |
|---|---|---|
transform |
(transformString: string) => Transform |
Parse a transform string like "grow-4 rotate-30" |
icon |
(iconString: string) => IconLookup |
Parse an icon string like "fas fa-user" |
Top-level functions:
| Function | Signature | Description |
|---|---|---|
noAuto |
() => void |
Disable automatic <i> to <svg> replacement |
findIconDefinition |
(lookup: IconLookup) => IconDefinition |
Find an icon in the library |
icon |
(icon: IconLookup, params?: IconParams) => { html, node, abstract } |
Generate an icon object |
text |
(content: string, params?: TextParams) => object |
Generate a text layer |
counter |
(content: string | number, params?: CounterParams) => object |
Generate a counter layer |
layer |
(assembler: Function, params?: LayerParams) => object |
Compose layers |
toHtml |
(abstractNodes: object[]) => string |
Convert abstract tree to HTML string |
Parameter interfaces:
interface IconParams {
title?: string;
titleId?: string;
classes?: string | string[];
attributes?: { [key: string]: string };
styles?: { [key: string]: string };
transform?: Transform | string;
symbol?: boolean | string;
mask?: IconLookup;
maskId?: string;
}
interface Transform {
size?: number; // default 16 (1em)
x?: number; // horizontal shift
y?: number; // vertical shift
rotate?: number; // degrees
flipX?: boolean;
flipY?: boolean;
}
Prop types for CSS class equivalents:
| Type | Values |
|---|---|
SizeProp |
"2xs", "xs", "sm", "lg", "xl", "2xl", "1x" through "10x" |
FlipProp |
"horizontal", "vertical", "both" |
PullProp |
"left", "right" |
RotateProp |
90, 180, 270 |
8.4 CSS Utility Classes Reference
Sizing classes:
| Class | Scale |
|---|---|
fa-2xs |
0.625em |
fa-xs |
0.75em |
fa-sm |
0.875em |
fa-lg |
1.25em |
fa-xl |
1.5em |
fa-2xl |
2em |
fa-1x through fa-10x |
1em through 10em |
fa-11x through fa-20x |
11em through 20em (extended set) |
Animation classes:
| Class | Effect |
|---|---|
fa-beat |
Pulsing scale animation |
fa-fade |
Opacity fade animation |
fa-beat-fade |
Combined beat + fade |
fa-bounce |
Vertical bounce |
fa-flip |
3D flip animation |
fa-shake |
Horizontal shake |
fa-spin |
Continuous 360-degree rotation |
fa-spin-pulse |
Stepped rotation (8 steps) |
fa-spin-reverse |
Counter-clockwise spin |
Layout classes:
| Class | Effect |
|---|---|
fa-fw |
Fixed-width icon (uniform width for alignment) |
fa-width-auto |
Auto width (new in v7) |
fa-width-fixed |
Fixed width (new in v7, explicit version of fa-fw) |
fa-border |
Adds a border around the icon |
fa-pull-left |
Float left |
fa-pull-right |
Float right |
fa-pull-start |
Logical start (LTR/RTL aware) |
fa-pull-end |
Logical end (LTR/RTL aware) |
fa-inverse |
Inverted color (white) |
Rotation and flip classes:
| Class | Effect |
|---|---|
fa-rotate-90 |
90-degree rotation |
fa-rotate-180 |
180-degree rotation |
fa-rotate-270 |
270-degree rotation |
fa-rotate-by |
Rotate by CSS custom property --fa-rotate-angle |
fa-flip-horizontal |
Horizontal mirror |
fa-flip-vertical |
Vertical mirror |
fa-flip-both |
Both axes mirror |
Stacking classes:
| Class | Purpose |
|---|---|
fa-stack |
Container for stacked icons |
fa-stack-1x |
Regular-sized icon in a stack |
fa-stack-2x |
Larger background icon in a stack |
Layering classes:
| Class | Purpose |
|---|---|
fa-layers |
Container for layered icons |
fa-layers-text |
Text element in a layer |
fa-layers-counter |
Counter badge in a layer |
fa-layers-bottom-left |
Position: bottom-left |
fa-layers-bottom-right |
Position: bottom-right |
fa-layers-top-left |
Position: top-left |
fa-layers-top-right |
Position: top-right |
List classes:
| Class | Purpose |
|---|---|
fa-ul |
Icon list container |
fa-li |
List item icon |
Duotone classes (Pro only, architecturally present):
| Class | Purpose |
|---|---|
fa-swap-opacity |
Swap primary/secondary opacity |
fa-primary |
Target primary layer |
fa-secondary |
Target secondary layer |
duotone-group |
Duotone group container |
8.5 Import Macro System
Font Awesome provides a babel-plugin-macros integration for compile-time icon resolution. This eliminates the need for explicit imports and library registration at runtime.
Prerequisites:
babel-plugin-macrosinstalled and configured in Babel@babel/helper-module-importsavailable
Supported macros:
| Macro | Resolves To |
|---|---|
solid('icon-name') |
Solid icon definition import |
regular('icon-name') |
Regular icon definition import |
light('icon-name') |
Light icon definition import (Pro) |
thin('icon-name') |
Thin icon definition import (Pro) |
duotone('icon-name') |
Duotone icon definition import (Pro) |
brands('icon-name') |
Brands icon definition import |
icon('prefix', 'icon-name') |
Generic icon definition import |
Constraints:
- Icon name must NOT start with
fa-(use'user', not'fa-user') - Only string literals are supported (no variables or template literals)
- License must be configured:
'free'or'pro'
Warning
The macro transpiles at build time. Dynamic icon names (computed from variables) cannot be resolved and will produce a build error. Use the runtime
library.add()+findIconDefinition()pattern for dynamic icon selection.
Example usage:
import { solid, brands } from '@fortawesome/fontawesome-svg-core/import.macro';
const userIcon = solid('user'); // Transpiles to: import { faUser } from '@fortawesome/free-solid-svg-icons'
const githubIcon = brands('github'); // Transpiles to: import { faGithub } from '@fortawesome/free-brands-svg-icons'
8.6 Conflict Detection Module
conflict-detection.js detects multiple Font Awesome versions loaded on the same page. It operates by:
- Scanning the DOM for all
<script>and<link>elements - Computing MD5 hashes of inline script content
- Testing each node against known Font Awesome identification patterns
- Reporting results via
console.info()andconsole.table()
Output categories:
- Conflicts detected — multiple FA versions found, with details of each
- No conflicts — single version confirmed
- Timed-out tests — some detection patterns did not complete (typically on very large pages)
Load it alongside your main FA scripts:
<script src="/js/conflict-detection.min.js"></script>
8.7 SVG Viewbox Variants
Icons ship in two viewBox formats:
| Directory | ViewBox | Description |
|---|---|---|
svgs/ |
Cropped to icon content | Tighter bounding box, varies per icon |
svgs-full/ |
0 0 640 640 |
Uniform dimensions, consistent spacing |
Note
GitHub issue #20870 reports broken viewBox values for several icons. If icons appear clipped, compare the
svgs/andsvgs-full/versions. The full-viewBox variants atsvgs-full/are not affected.
9. Integration Points
9.1 v4 and v5 Compatibility Shims
Font Awesome 7 provides backward compatibility for v4 and v5 class names through shim files:
v4 shims:
css/v4-shims.min.css— CSS class mappings from v4 names to v7js/v4-shims.min.js— JavaScript v4 to v7 name resolutioncss/v4-font-face.min.css—@font-facedeclarations using v4 font family namesscss/v4-shims.scss— SCSS source for v4 compatibilitymetadata/shims.yml— canonical v4 to v7 name mapping data
v5 shims:
css/v5-font-face.min.css—@font-facedeclarations using v5 font family names
Migration approach:
- Add the appropriate shim file alongside your main FA 7 CSS/JS
- Existing v4/v5 markup continues to work without modification
- Gradually update class names to v7 equivalents
- Remove shim files once all markup is updated
The shims.yml metadata file provides a machine-readable mapping for automated migration scripts.
9.2 Framework Integration Patterns
React (@fortawesome/react-fontawesome):
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
import { faUser } from '@fortawesome/free-solid-svg-icons';
<FontAwesomeIcon icon={faUser} size="2x" spin />
Vue (@fortawesome/vue-fontawesome):
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome';
import { library } from '@fortawesome/fontawesome-svg-core';
import { faUser } from '@fortawesome/free-solid-svg-icons';
library.add(faUser);
// In template: <font-awesome-icon icon="fa-solid fa-user" />
Angular (@fortawesome/angular-fontawesome):
import { FaIconLibrary } from '@fortawesome/angular-fontawesome';
import { faUser } from '@fortawesome/free-solid-svg-icons';
constructor(library: FaIconLibrary) {
library.addIcons(faUser);
}
// In template: <fa-icon [icon]="['fas', 'user']"></fa-icon>
Tip
Framework wrapper packages are separate from this distribution. Install the wrapper matching your framework version. The icon packages (
free-solid-svg-icons, etc.) andfontawesome-svg-coreare shared dependencies across all framework wrappers.
9.3 SVG in CSS Backgrounds
Using Font Awesome SVGs as CSS background images:
.icon-user {
background-image: url('/svgs/solid/user.svg');
background-size: contain;
background-repeat: no-repeat;
width: 1em;
height: 1em;
}
When generating SVG via the JavaScript API for use in CSS background-image or content properties, add the xmlns attribute:
import { icon } from '@fortawesome/fontawesome-svg-core';
import { faUser } from '@fortawesome/free-solid-svg-icons';
const svgHtml = icon(faUser).html[0];
// Note: icon() output may lack xmlns for CSS background usage
// See GitHub issue #21519
Warning
GitHub issue #21519 reports that SVG output from
icon()does not include thexmlnsattribute, which is required for SVG used in CSSbackground-imagecontexts. Addxmlns="http://www.w3.org/2000/svg"manually to the generated SVG string.
9.4 Accessibility
Font Awesome icons are decorative by default. The SVG+JS engine adds aria-hidden="true" to generated <svg> elements.
For meaningful icons (icons that convey information), add a title:
<!-- CSS + Web Fonts -->
<i class="fa-solid fa-exclamation-triangle" role="img" aria-label="Warning"></i>
<!-- SVG + JS (title param) -->
<i class="fa-solid fa-exclamation-triangle" data-fa-title="Warning" data-fa-title-id="warning-1"></i>
Via the JavaScript API:
icon(faExclamationTriangle, { title: 'Warning', titleId: 'warning-1' });
// Produces: <svg aria-labelledby="warning-1"><title id="warning-1">Warning</title>...</svg>
Important
GitHub issue #20729 reports that v7 no longer renders the
<title>element in certain configurations. Verify<title>rendering in your specific setup and version.
9.5 Known Width Behavior Change in v7
Font Awesome 7 defaults to fixed-width icons (unlike v6 which defaulted to variable width). This ensures alignment in navigation menus and lists but may affect layouts designed for v6's variable-width default.
fa-fw— explicitly set fixed widthfa-width-auto— opt out of fixed width (new in v7)fa-width-fixed— explicitly set fixed width (new in v7, same asfa-fw)- CSS custom properties:
--fa-widthand--fa-displaycontrol width behavior
GitHub issue #21473 discusses opting out of fixed-width icons in v7 Kit deployments.
Note
GitHub issue #21518 reports that
--fa-widthand--fa-displayCSS custom properties are not defined when using the React SVG approach. These properties are only set by the CSS files, not the SVG+JS rendering engine.
9.6 Troubleshooting Reference
| Issue | Symptom | Resolution | Reference |
|---|---|---|---|
| Duplicated icons in print | Firefox/Safari render doubled icons when printing SVG+JS pages | Use CSS+Web Fonts for print stylesheets, or add @media print rules to hide SVG duplicates |
#20848 |
| Missing module error | Cannot find module '@fortawesome-internal-tools/...' |
Internal build dependency leaked into error output; does not affect runtime | #20307 |
| Icons clipped at top/bottom | SVG viewBox too small for icon content | Use svgs-full/ versions with 640x640 viewBox |
#20733, #20870 |
| npm install 404 errors | npm.fontawesome.com returns 404 or redirect failures |
Registry migration to Cloudsmith; check .npmrc for stale registry URLs |
#21526, #21527 |
| Slow WOFF2 loading | fa-solid-900.woff2 takes excessive time |
Preload font: <link rel="preload" as="font" type="font/woff2"> |
#21461 |
| Vertical misalignment | Specific icons (e.g., fa-battery-empty) vertically offset |
Verify icon viewBox; may require CSS vertical-align adjustment |
#21553 |
| Incorrect class matching | ICON_SELECTION_SYNTAX_PATTERN regex matches unintended elements |
Ensure CSS classes follow fa-{style} fa-{name} pattern exactly |
#21531 |
| Tree shaking not working | Full icon pack included despite individual imports | Ensure bundler sideEffects: false and no barrel re-exports of entire packs |
#18020 |
9.7 Licensing
Font Awesome Free uses a three-part license:
| Component | License | Permissions |
|---|---|---|
| Icons (SVG files) | CC BY 4.0 | Use, modify, share with attribution |
| Fonts (WOFF2, TTF, OTF) | SIL OFL 1.1 | Use, modify, redistribute; cannot sell fonts alone |
| Code (CSS, JS, SCSS) | MIT | Use, modify, distribute, sublicense |
Attribution is required for icons under CC BY 4.0. Include "Font Awesome Free" with a link to fontawesome.com in your project's credits, documentation, or about page.