` element inside the SVG for screen readers: ```html ``` ### Recipe: CSS Pseudo-Elements Use Font Awesome icons in CSS `::before` and `::after` pseudo-elements (Web Fonts + CSS approach): ```css .icon-star::before { font-family: "Font Awesome 6 Free"; font-weight: 900; /* 900 = solid, 400 = regular */ content: "\f005"; /* Unicode for fa-star */ } ``` For SVG + JS, pseudo-element support must be explicitly enabled since it is off by default due to performance cost: ```javascript window.FontAwesomeConfig = { searchPseudoElements: true }; ``` > [!CAUTION] > Enabling `searchPseudoElements` in SVG + JS mode performs a full DOM scan looking for pseudo-elements that reference Font Awesome. This can significantly impact page load performance on large pages. Use sparingly and test thoroughly. ### Recipe: Migrating from v4 or v5 If upgrading from Font Awesome 4 or 5, use the compatibility shims to avoid rewriting all your markup at once: **CSS shims (load alongside your main CSS):** ```html ``` **JS shims (load alongside your main JS):** ```html ``` These map old icon names (e.g., `fa-star-o`, `fa-file-text`) to their v7 equivalents automatically. Once migration is complete, remove the shim files to reduce payload. --- ## 6. Troubleshooting ### Icons Not Showing (Blank Squares or Nothing) **Symptom:** Icons render as empty squares, question marks, or nothing at all. **Solutions:** 1. Verify the CSS or JS file is loading (check browser DevTools Network tab for 404s) 2. Confirm both required classes are present: a style prefix (`fa-solid`, `fa-regular`, or `fa-brands`) AND the icon name (`fa-house`, `fa-star`, etc.) 3. Check the icon exists in the Free edition — many icons are Pro-only 4. For Web Fonts + CSS: verify the `webfonts/` directory is accessible and the path from CSS to webfonts is correct (`../webfonts/` by default) 5. Clear browser cache — stale cached CSS can reference missing font files ### Icons Appear But Wrong Style **Symptom:** Requested a regular (outline) icon but getting a solid (filled) icon. **Explanation:** The Free edition has ~270 regular icons versus ~2,000+ solid icons. If a regular variant does not exist for a given icon, Font Awesome falls back to solid. Verify the icon you want has a regular variant available in the Free edition. ### Web Font Files Load Slowly **Symptom:** Icons flash or appear late, especially `fa-solid-900.woff2`. **Solutions:** 1. Preload the font file: ```html ``` 2. Host fonts on a CDN closer to your users 3. Subset to only the styles you need (load `solid.css` instead of `all.css`) 4. Consider switching to SVG + JS if you only use a few icons (tree-shaking drastically reduces payload) ### SVG + JS: Icons Not Replacing **Symptom:** `` tags remain in the DOM instead of becoming `

# Font Awesome User Guide **Font Awesome 7.2.0 Free** — the iconic font, CSS, and SVG icon framework. This guide covers everything you need to add 2,800+ icons to your web projects using either the Web Fonts + CSS approach or the SVG + JavaScript approach. | Detail | Value | |--------|-------| | Version | 7.2.0 (Free edition) | | Package | `@fortawesome/fontawesome-free` | | Icons (Free) | ~2,000+ solid, ~270+ regular, ~580+ brands | | License | Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT | --- ## 1. Quick Start ### CDN — Fastest Way to Get Started Add one line to your HTML `` and start using icons immediately: ```html ``` That loads Web Fonts + CSS for all three Free icon families. Icons render as `` elements with two classes: a **style prefix** and an **icon name**. > [!TIP] > If you only need one icon family (e.g., solid icons), load just `solid.css` and `fontawesome.css` instead of `all.css` to reduce payload size. ### SVG + JS Alternative If you prefer SVG rendering over web fonts, use the JavaScript bundle instead: ```html ``` The JS bundle automatically finds `` elements and replaces them with inline ` tags with SVGs, watches for new ones ``` ### Composer (PHP Projects) ```bash composer require fortawesome/font-awesome ``` ### Manual Download Download the release archive from GitHub, extract it, and reference the files from `css/` and `webfonts/` (for Web Fonts + CSS) or from `js/` (for SVG + JS). Place the directories in your project's public/static assets folder. When self-hosting Web Fonts + CSS, maintain this directory relationship: ``` your-project/ assets/ css/ all.min.css (or individual: 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/` by default, so the `webfonts/` directory must be one level up from the `css/` directory. > [!IMPORTANT] > If you place the webfonts in a different location relative to the CSS, you must update the `$fa-font-path` SCSS variable or manually adjust the `@font-face` `src` paths. ### Choosing Your Approach | Feature | Web Fonts + CSS | SVG + JS | |---------|----------------|----------| | Setup complexity | Lower | Slightly higher | | Rendering | Font glyphs | Inline SVG | | Accessibility | Needs `aria-hidden` | Auto `aria-hidden` on SVGs | | Styling | CSS `color`, `font-size` | CSS `color`, `width`/`height` | | Animations | CSS classes | CSS classes | | Layering/Stacking | Both supported | Both supported | | Performance | Single font download | JS parse + DOM manipulation | | Power transforms | Not available | Available via `data-fa-transform` | | Pseudo-elements | Works naturally | Requires `searchPseudoElements` config | --- ## 3. Configuration ### SVG + JS Configuration When using the JavaScript approach, Font Awesome exposes a `config` object you can modify before loading: ```html ``` Set `window.FontAwesomeConfig` **before** loading the Font Awesome JS bundle. Any properties not specified use the defaults shown above. > [!TIP] > For most projects, the defaults work perfectly. Only modify config if you have a specific need, such as enabling pseudo-element scanning or disabling automatic replacement for manual control. ### Configuration Reference | Property | Default | Description | |----------|---------|-------------| | `autoReplaceSvg` | `true` | Automatically replace `` elements with `` | | `observeMutations` | `true` | Watch DOM via MutationObserver for dynamically added icons | | `searchPseudoElements` | `false` | Scan CSS pseudo-elements (`::before`, `::after`) for icon references | | `showMissingIcons` | `true` | Show a question-mark placeholder for icons not found in the library | | `measurePerformance` | `false` | Log timing metrics to the browser console | | `keepOriginalSource` | `true` | Preserve the original `` element as a comment node | | `styleDefault` | `'solid'` | Default icon style when none specified | | `familyDefault` | `'classic'` | Default icon family | | `cssPrefix` | `'fa'` | CSS class prefix for icon elements | | `replacementClass` | `'svg-inline--fa'` | Class applied to generated SVG elements | | `mutateApproach` | `'async'` | DOM mutation timing: `'async'` or `'sync'` | See the Admin Guide for advanced configuration scenarios and performance tuning. ### SCSS Customization If using the SCSS source files, you can override variables before importing: ```scss // Override the font path for your project structure $fa-font-path: "../fonts"; // Then import Font Awesome @import "@fortawesome/fontawesome-free/scss/fontawesome"; @import "@fortawesome/fontawesome-free/scss/solid"; @import "@fortawesome/fontawesome-free/scss/regular"; @import "@fortawesome/fontawesome-free/scss/brands"; ``` Available SCSS partials: `_animated.scss`, `_bordered.scss`, `_core.scss`, `_functions.scss`, `_icons.scss`, `_list.scss`, `_mixins.scss`, `_pulled.scss`, `_rotated-flipped.scss`, `_sizing.scss`, `_stacked.scss`, `_variables.scss`, `_widths.scss`. See the Admin Guide for the full list of SCSS variables and advanced theming options. --- ## 4. Core Usage ### Icon Families and Styles (Free Edition) Font Awesome Free includes three styles in the **Classic** family: | Style | Prefix Class | Short Prefix | Description | |-------|-------------|--------------|-------------| | Solid | `fa-solid` | `fas` | Filled icons, largest collection (~2,000+) | | Regular | `fa-regular` | `far` | Outlined/lighter icons (~270+) | | Brands | `fa-brands` | `fab` | Company and product logos (~580+) | ```html ``` > [!NOTE] > Pro users have access to many additional families (Sharp, Duotone, and more). In the Free edition, stick with `fa-solid`, `fa-regular`, and `fa-brands`. ### Sizing Icons Font Awesome provides relative and literal sizing classes: **Relative sizes** (relative to the parent container's font size): | Class | Size | |-------|------| | `fa-2xs` | 0.625em | | `fa-xs` | 0.75em | | `fa-sm` | 0.875em | | *(default)* | 1em | | `fa-lg` | 1.25em | | `fa-xl` | 1.5em | | `fa-2xl` | 2em | **Literal sizes** (exact multiples of the base): `fa-1x`, `fa-2x`, `fa-3x`, `fa-4x`, `fa-5x`, `fa-6x`, `fa-7x`, `fa-8x`, `fa-9x`, `fa-10x` ```html ``` ### Fixed-Width and Auto-Width Icons Use `fa-fw` to give all icons the same width, which is essential for vertically aligning icons in navigation menus or lists: ```html

Home

Settings

Profile

``` > [!IMPORTANT] > In Font Awesome 7, icons default to fixed width. If you need auto-width (fitting the icon's natural aspect ratio), use `fa-width-auto`. To explicitly request fixed width, use `fa-width-fixed`. These are new v7 classes. ```html ``` ### Rotating and Flipping ```html ``` ### Animating Icons Apply animation classes for attention-grabbing effects: ```html ``` Reverse the spin direction: ```html ``` Customize animation timing with CSS custom properties: ```html ``` ### Bordered and Pulled Icons Create pull-quote style layouts with bordered, floated icons: ```html Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. ``` ### Lists with Icons Replace default list bullets with icons: ```html

Item one

Item two

Loading...

``` --- ## 5. Common Tasks ### Recipe: Loading Spinner ```html ``` ### Recipe: Icon Button Toolbar ```html

``` ### Recipe: Social Media Links ```html

``` ### Recipe: Stacking Icons Layer two icons on top of each other: ```html ``` The `fa-stack-2x` icon is the background layer (larger), and `fa-stack-1x` is the foreground (smaller). Use `fa-inverse` to flip the foreground icon to white. ### Recipe: Layering Icons, Text, and Counters (SVG + JS) The layering system provides more flexible composition than stacking: ```html 12 NEW ``` Position counters with placement classes: ```html 5 99+ ``` Available positions: `fa-layers-top-left`, `fa-layers-top-right`, `fa-layers-bottom-left`, `fa-layers-bottom-right`. > [!NOTE] > Power transforms (`data-fa-transform`) like `shrink-6`, `up-2`, `rotate-45` are only available with the SVG + JS approach. They do not work with Web Fonts + CSS. ### Recipe: SVG + JS Power Transforms With the JavaScript approach, you get fine-grained positioning and sizing control: ```html ``` Available transforms: `grow-{n}`, `shrink-{n}`, `up-{n}`, `down-{n}`, `left-{n}`, `right-{n}`, `rotate-{n}`, `flip-v`, `flip-h`. ### Recipe: Using the JavaScript API Directly For dynamic icon generation in JavaScript applications: ```javascript import { library, icon } from '@fortawesome/fontawesome-svg-core'; import { faCamera, faStar } from '@fortawesome/free-solid-svg-icons'; library.add(faCamera, faStar); // Generate an icon const cameraIcon = icon({ prefix: 'fas', iconName: 'camera' }); console.log(cameraIcon.html); // Array of HTML strings // Insert into the DOM document.getElementById('my-icon').innerHTML = cameraIcon.html[0]; ``` ### Recipe: Composing Layers Programmatically ```javascript import { library, icon, text, counter, layer, toHtml } from '@fortawesome/fontawesome-svg-core'; import { faCircle, faEnvelope } from '@fortawesome/free-solid-svg-icons'; library.add(faCircle, faEnvelope); // Generate a text layer const label = text('Hello', { transform: { size: 12 } }); // Generate a counter const badge = counter('42'); // Compose layers const composed = layer((push) => { push(icon({ prefix: 'fas', iconName: 'circle' })); push(text('7', { transform: { size: 10 }, classes: ['fa-inverse'] })); }); document.getElementById('badge').innerHTML = toHtml(composed.abstract); ``` ### Recipe: Manual SVG Replacement If you set `autoReplaceSvg: false` or call `noAuto()`, trigger replacement manually: ```javascript import { dom, noAuto } from '@fortawesome/fontawesome-svg-core'; noAuto(); // Disable automatic replacement // Later, when ready: dom.i2svg().then(() => { console.log('Icons replaced'); }); // Or start watching the DOM for new icons dom.watch(); ``` ### Recipe: Finding Icon Definitions at Runtime ```javascript import { findIconDefinition, library } from '@fortawesome/fontawesome-svg-core'; import { faStar } from '@fortawesome/free-solid-svg-icons'; library.add(faStar); const starDef = findIconDefinition({ prefix: 'fas', iconName: 'star' }); // Returns: { prefix: 'fas', iconName: 'star', icon: [width, height, ligatures, unicode, svgPathData] } ``` ### Recipe: Using SVG Sprites Font Awesome ships SVG sprite files for each icon family: ```html ``` ```css .icon { width: 1em; height: 1em; fill: currentColor; vertical-align: -0.125em; } ``` ### Recipe: Inline SVG Files Every icon is available as an individual SVG file under `svgs/{style}/{icon-name}.svg`: ```html ``` Or inline the SVG for full CSS control over color and sizing: ```html ``` ### Recipe: Tree-Shaking with Webpack Import only the icons you use to keep bundle sizes small: ```javascript // Only these four icons will be included in your bundle import { library, dom } from '@fortawesome/fontawesome-svg-core'; import { faHome, faUser, faCog } from '@fortawesome/free-solid-svg-icons'; import { faGithub } from '@fortawesome/free-brands-svg-icons'; library.add(faHome, faUser, faCog, faGithub); dom.watch(); ``` > [!WARNING] > Avoid importing the entire icon package (e.g., `import { fas } from '@fortawesome/free-solid-svg-icons'`) if you only need a few icons. Each family package exports every icon, so a wildcard import pulls them all into your bundle. Always destructure the specific icons you need. ### Recipe: Babel Macro for Automatic Tree-Shaking Font Awesome includes a Babel macro (`import.macro.js`) for concise, tree-shaken imports: ```javascript import { solid, regular, brands } from '@fortawesome/fontawesome-svg-core/import.macro'; // Each call returns only that icon's definition const star = solid('star'); const heart = regular('heart'); const github = brands('github'); ``` Configure in `babel-plugin-macros.config.js`: ```javascript module.exports = { 'fontawesome-svg-core': { license: 'free' } }; ``` ### Recipe: Accessibility Best Practices **Decorative icons** (purely visual, adjacent to visible text): ```html Settings ``` **Semantic icons** (convey meaning without adjacent text): ```html Settings ``` When using the SVG + JS approach, Font Awesome automatically adds `aria-hidden="true"` to generated `