Warning

# Font Awesome Administrator & Developer Guide 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 | `` 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 `` elements with inline `` to `` - **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 `` tags with `` 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 `` 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 ``. ### 3.2 Setting Configuration **Before loading (SVG+JS global script):** ```html ``` **After loading (SVG Core API):** ```javascript 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`: ```javascript // 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:** ```html ``` **SVG + JS via CDN:** ```html ``` > [!WARNING] > CDN availability issues have been reported. GitHub issue [#21526](https://github.com/FortAwesome/Font-Awesome/issues/21526) documents `npm.fontawesome.com` returning 404 errors due to a Cloudsmith redirect change. Issue [#21527](https://github.com/FortAwesome/Font-Awesome/issues/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:** ```scss $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: ```bash 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:** ```javascript 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](https://github.com/FortAwesome/Font-Awesome/issues/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: ```html ``` ### 4.5 Selective Loading (JS Approach) ```html ``` ### 4.6 SVG Sprites Deployment SVG sprites offer a middle ground: no JavaScript, no font loading, but requires `` references. ```html ``` 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: ```nginx # 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 `` and ` ``` ### 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](https://github.com/FortAwesome/Font-Awesome/issues/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`):** ```javascript import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'; import { faUser } from '@fortawesome/free-solid-svg-icons'; ``` **Vue (`@fortawesome/vue-fontawesome`):** ```javascript 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: ``` **Angular (`@fortawesome/angular-fontawesome`):** ```typescript import { FaIconLibrary } from '@fortawesome/angular-fontawesome'; import { faUser } from '@fortawesome/free-solid-svg-icons'; constructor(library: FaIconLibrary) { library.addIcons(faUser); } // In template: ``` > [!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: ```css .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: ```javascript 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](https://github.com/FortAwesome/Font-Awesome/issues/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 ` ``` Via the JavaScript API: ```javascript icon(faExclamationTriangle, { title: 'Warning', titleId: 'warning-1' }); // Produces: ``` > [!IMPORTANT] > GitHub issue [#20729](https://github.com/FortAwesome/Font-Awesome/issues/20729) reports that v7 no longer renders the `` 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](https://github.com/FortAwesome/Font-Awesome/issues/21473) discusses opting out of fixed-width icons in v7 Kit deployments. > [!NOTE] > GitHub issue [#21518](https://github.com/FortAwesome/Font-Awesome/issues/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](https://github.com/FortAwesome/Font-Awesome/issues/20848) | | Missing module error | `Cannot find module '@fortawesome-internal-tools/...'` | Internal build dependency leaked into error output; does not affect runtime | [#20307](https://github.com/FortAwesome/Font-Awesome/issues/20307) | | Icons clipped at top/bottom | SVG viewBox too small for icon content | Use `svgs-full/` versions with 640x640 viewBox | [#20733](https://github.com/FortAwesome/Font-Awesome/issues/20733), [#20870](https://github.com/FortAwesome/Font-Awesome/issues/20870) | | npm install 404 errors | `npm.fontawesome.com` returns 404 or redirect failures | Registry migration to Cloudsmith; check `.npmrc` for stale registry URLs | [#21526](https://github.com/FortAwesome/Font-Awesome/issues/21526), [#21527](https://github.com/FortAwesome/Font-Awesome/issues/21527) | | Slow WOFF2 loading | `fa-solid-900.woff2` takes excessive time | Preload font: `<link rel="preload" as="font" type="font/woff2">` | [#21461](https://github.com/FortAwesome/Font-Awesome/issues/21461) | | Vertical misalignment | Specific icons (e.g., `fa-battery-empty`) vertically offset | Verify icon viewBox; may require CSS `vertical-align` adjustment | [#21553](https://github.com/FortAwesome/Font-Awesome/issues/21553) | | Incorrect class matching | `ICON_SELECTION_SYNTAX_PATTERN` regex matches unintended elements | Ensure CSS classes follow `fa-{style} fa-{name}` pattern exactly | [#21531](https://github.com/FortAwesome/Font-Awesome/issues/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](https://github.com/FortAwesome/Font-Awesome/issues/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. --- _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. Unofficial; not affiliated with or reviewed by the project._