Jesse A. Green / notebook

Font Awesome Administrator & Developer Guide

Generated May 2026 from FortAwesome/Font-Awesome at 337dd20

AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it.

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) and all.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 ::before and ::after pseudo-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) — uses requestAnimationFrame for 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, and fab resolve 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, and autoAddCss: 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.com returning 404 errors due to a Cloudsmith redirect change. Issue #21527 reports 301 redirects to cloudsmith.io causing 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: false in 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:

  1. Replace all asset files (css/, js/, webfonts/, etc.)
  2. Update CDN URLs if using CDN references
  3. Update integrity hashes on all <link> and <script> tags
  4. If using NPM: npm update @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons (etc.)
  5. Check shims.yml for any removed icon name mappings
  6. Test with conflict-detection.js to ensure no old versions remain
  7. 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 DOMContentLoaded to find and replace icon elements
  • MutationObserver: Ongoing cost for watching DOM changes (disable with observeMutations: false for static pages)
  • Pseudo-element scanning: Expensive when enabled. searchPseudoElements: true triggers getComputedStyle() calls across the DOM. searchPseudoElementsFullScan: true makes 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) requires style-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-macros installed and configured in Babel
  • @babel/helper-module-imports available

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:

  1. Scanning the DOM for all <script> and <link> elements
  2. Computing MD5 hashes of inline script content
  3. Testing each node against known Font Awesome identification patterns
  4. Reporting results via console.info() and console.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/ and svgs-full/ versions. The full-viewBox variants at svgs-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 v7
  • js/v4-shims.min.js — JavaScript v4 to v7 name resolution
  • css/v4-font-face.min.css — @font-face declarations using v4 font family names
  • scss/v4-shims.scss — SCSS source for v4 compatibility
  • metadata/shims.yml — canonical v4 to v7 name mapping data

v5 shims:

  • css/v5-font-face.min.css — @font-face declarations using v5 font family names

Migration approach:

  1. Add the appropriate shim file alongside your main FA 7 CSS/JS
  2. Existing v4/v5 markup continues to work without modification
  3. Gradually update class names to v7 equivalents
  4. 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.) and fontawesome-svg-core are 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 the xmlns attribute, which is required for SVG used in CSS background-image contexts. Add xmlns="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 width
  • fa-width-auto — opt out of fixed width (new in v7)
  • fa-width-fixed — explicitly set fixed width (new in v7, same as fa-fw)
  • CSS custom properties: --fa-width and --fa-display control width behavior

GitHub issue #21473 discusses opting out of fixed-width icons in v7 Kit deployments.

Note

GitHub issue #21518 reports that --fa-width and --fa-display CSS 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.