# Configuration Guide to configuring Font Awesome using JavaScript for custom icon setups. > Control features of Font Awesome SVG with JavaScript using the properties below. Make sure you already: - [Set up access](/apis/javascript.md) to the Javascript API in your project. ## Options |
Name
|
Default
| Purpose | | :----------------------------------- | :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `autoAddCss` | `true` | Insert the supporting CSS into the `` of the HTML document? | | `autoReplaceSvg` | `true`\* | Set to `true` to replace any elements that look like icons with the inline SVG. Set to `nest` to insert SVGs as child elements. | | `cssPrefix` | `'fa'` | Class prefix for icons and CSS styles like `fa-spin`. This property was previously called `familyPrefix`. `familyPrefix` can still be used, but it may be confusing now with our Family icon styles. | | `familyDefault` | `'classic'` | Font Awesome Classic is the default if this is NOT specified. For Sharp icons, just add `sharp` in the same manner! | | `keepOriginalSource` | `true` | If replacing with inline SVG keep an HTML comment `<-- -->` with the original markup | | `measurePerformance` | `false` | For supporting browsers, add markers in the Performance section of developer tools? | | `observeMutations` | `true`\* | Watch the DOM for any changes and add, replace, or modify icons on-the-fly | | `mutateApproach` | `async` | **version >=5.8.0** Can be `async` or `sync`. If `async` will make replace icons using `requestAnimationFrame` | | `replacementClass` | `'svg-inline--fa'` | Main CSS class for `` tags replacements. All replacements will have this class. | | `searchPseudoElements` | `false` | Searches stylesheets for elements with a Font Awesome CSS `font-family` and `content` property and replaces with inline SVG | | `searchPseudoElementsWarnings` | `true` | Emit `console.warn` messages if a stylesheet can't be parsed when using `searchPseudoElements`. | | `searchPseudoElementsFullScan` | `false` | Searches DOM tree for elements with a Font Awesome `font-family` and `content` property and replaces with inline SVG. Warning, this is slow! | | `showMissingIcons` | `true` | If an icon cannot be found show an animated "missing" icon in its place | | `styleDefault` | `'solid'` | If an icon's style is not set or cannot be found, the icon's default style will be `'solid'` |

Keep In Mind

Using the `@fortawesome/fontawesome-svg-core` package disables `autoReplaceSvg` and `observeMutations` by default. ## Accessing the configuration When using the `@fortawesome/fontawesome-svg-core` package: ```js import { config } from '@fortawesome/fontawesome-svg-core' console.log(config.autoAddCss) // true ``` When using a package that provides access to the API through the browser: ```html ``` ## Setting the configuration Setting just one option using `@fortawesome/fontawesome-svg-core`: ```js import { config } from '@fortawesome/fontawesome-svg-core' config.autoAddCss = true ``` Using a ` ``` ```html ``` You can also set configuration values to true by simply adding the attribute without a value. ```html ``` If you can't add any attributes to a ` ``` ## autoAddCss Font Awesome requires some base CSS styles to display icons at the correct color and size and to enable the other styling options. When this option is `true` (default) these styles are automatically inserted into the `` of the DOM. ## autoReplaceSvg When `true` (default) this will cause Font Awesome to search through the DOM for any `` tags and automatically replace them with `` tags. ```html ``` For example this `` tag: ```html ``` Will be replaced with this `` tag: ```html ``` ## autoReplaceSvg through nesting By default Font Awesome will replace elements. However, setting this value to `nest` will cause Font Awesome to add a child element to the existing `` tag. ```html ``` This `` tag: ```html ``` Will be nested within the existing tag: ```html ```

Are you using the dom.i2svg() method?

The `data-fa-i2svg` attribute is used to denote and track any tag that has been modified by Font Awesome using the `dom.i2svg()` method. This allows the library to efficiently watch these for changes and to ignore them for other operations. You can use this data attribute to target nodes that have been modified by Font Awesome. ## cssPrefix Used to modify the **css prefix for the icon names**. By changing this from `fa` to `icon` we would replace `fa-kiwi-bird` with `icon-kiwi-bird`. ```html ``` To use the icon you would then use the following markup. ```html ```

Family vs. Style

The `cssPrefix` property was previously called `familyPrefix`. `familyPrefix` can still be used, but it may be confusing now with our Family icon styles. It's fairly common to confuse the previously used `familyPrefix` property for the icon with the style prefix which chooses solid, regular, light, or brands. Don't let this trip you up! You could also change `familyPrefix` to `cssPrefix` to help avoid confusion. ## familyDefault You can specify a default family for the icons in your project with `defaultFamily`. Below is an example on how to set the default family to `sharp`, with a default style of `solid`: ```js config.familyDefault = 'sharp' ``` ## keepOriginalSource When using `autoReplaceSvg` or manually calling `dom.i2svg()` you have the option to retain the original `` tag as a comment underneath the replacement `` tag. This is beneficial for debugging but does clutter the DOM a little. ```html ``` You can change the default value of `keepOriginalSource` to `false`: ```html ``` Will prevent Font Awesome from adding the comment: ```html ``` ## observeMutations When your project first loads and you have enabled `autoReplaceSvg`, Font Awesome will search through your document for `` tags and replace them with SVG icons. When additional changes occur to the page, through user interaction or by other means, and icons are modified or they are added to the page by placing more `` tags in the DOM Font Awesome needs to kick into gear again and do the same type of work it did when the page first loaded. You can tell Font Awesome to watch your page for changes using [MutationObservers](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) by setting `observeMutations` to `true` (default). ```html ``` ## mutateApproach Replacing icons with SVG actually happens in two steps: 1. Icons are parsed to pull out information such as icon name, family, style, and any additional stuff like Power Transforms 1. The necessary DOM changes are queued in a JavaScript array The reason this happens in two steps is to reduce [jank](https://developers.google.com/web/fundamentals/performance/rendering): the costly and visual reduction of performance as your page renders. After the array of DOM changes are computed they are, by default, registered in a function to be ran by calling `window.requestAnimationFrame()`. This optimizes the changes in the DOM to a period of time in the browser's lifecyle that makes it the most effecient. While this does increase performance it can cause a flash in the browser when the icons render since the rendering is asynchronous. In some environments this is not desirable and taking the additional performance hit of rendering the icons synchronously is worth the performance degradation. To force Font Awesome to immediately make the DOM changes after an icon is found for replacement you can use `sync`. ```html ``` ## searchPseudoElements

Using Pseudo-elements with JavaScript is not recommended

Although you can use pseudo-elements with SVG and JS we do not recommend using this method. It does not provide as many usage options, is difficult to configure, and is the slowest method of using Font Awesome. (Painfully slow in some cases.) By enabling `searchPseudoElements` to `true` (it's `false` by default) you can have Font Awesome search your stylesheets for any elements that have: 1. A Font Awesome matching [`font`](/web/add-icons/pseudo-elements.md#_2-reference-individual-icons) 1. A `content` property ```html ``` Make sure the `font-family` is set to a [valid Font Awesome font](/web/add-icons/pseudo-elements.md#font-families-and-styles-cheat-sheet), and the `font-weight` to its corresponding value! Note that `searchPseudoElements` does not work with stylesheets loaded from different domains (i.e. cross-origin). If your CSS is hosted on a different domain than your website and includes Font Awesome CSS pseudo-elements, those elements will not render as SVG icons. To address this, you can either add the attribute `crossorigin="anonymous"` to the `` element loading the stylesheet, or enable `searchPseudoElementsFullScan` for a slower but more thorough approach. ## searchPseudoElementsWarnings The `searchPseudoElementsWarnings` feature emits warnings to help identify if missing icons are caused by a problem with `searchPseudoElements`. You can disable these warnings if they are irrelevant by setting `searchPseudoElementsWarnings` to `false`. For example, if triggered by a cross-domain stylesheet that does not include Font Awesome icons, like a Google Fonts stylesheet. ## searchPseudoElementsFullScan While the `searchPseudoElements` feature scans the _stylesheets_ used on a page, the `searchPseudoElementsFullScan` feature scans the _entire DOM_. This can be useful when for some reason the stylesheet containing your Font Awesome CSS can't be parsed. One example is when your stylesheet is hosted on a different domain, where [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) can block its parsing. Keep in mind that this option is significantly slower, especially for large documents. ## showMissingIcons To help with debugging missing icons or mistyped icon names you can use `showMissingIcons` set to `true` (default) which will show a missing icon indicator. Here's an example: ```html ``` ## styleDefault You can specify a default style for the icons in your project with `styleDefault`. See below on how to do so -- all examples will set the default style to `light`: Using the Font Awesome three letter prefix ```js config.styleDefault = 'fal' ``` Using the style name only ```js config.styleDefault = 'light' ``` Using the `fa` prefix with the style name ```js config.styleDefault = 'fa-light' ```

Got default problems?

If the default style is not recognized, the style will default to `solid`. If the default family is not recognized, the family will default to `classic`.