Skip to content
Font Awesome Docs

Configuration

Control features of Font Awesome SVG with JavaScript using the properties below.

Options

Section titled “Options”
Name
Default
Purpose
autoAddCsstrueInsert the supporting CSS into the <head> of the HTML document?
autoReplaceSvgtrue*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!
keepOriginalSourcetrueIf replacing with inline SVG keep an HTML comment <-- --> with the original markup
measurePerformancefalseFor supporting browsers, add markers in the Performance section of developer tools?
observeMutationstrue*Watch the DOM for any changes and add, replace, or modify icons on-the-fly
mutateApproachasyncversion >=5.8.0 Can be async or sync. If async will make replace icons using requestAnimationFrame
replacementClass'svg-inline--fa'Main CSS class for <svg> tags replacements. All replacements will have this class.
searchPseudoElementsfalseSearches stylesheets for elements with a Font Awesome CSS font-family and content property and replaces with inline SVG
searchPseudoElementsWarningstrueEmit console.warn messages if a stylesheet can’t be parsed when using searchPseudoElements.
searchPseudoElementsFullScanfalseSearches DOM tree for elements with a Font Awesome font-family and content property and replaces with inline SVG. Warning, this is slow!
showMissingIconstrueIf 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'

Accessing the configuration

Section titled “Accessing the configuration”

When using the @fortawesome/fontawesome-svg-core package:

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:

<script>
  alert(window.FontAwesome.config)
</script>

Setting the configuration

Section titled “Setting the configuration”

Setting just one option using @fortawesome/fontawesome-svg-core:

import { config } from '@fortawesome/fontawesome-svg-core'
config.autoAddCss = true

Using a <script> tag in the browser:

<html>
  <head>
    <script
      src="https://example.com/fontawesome/js/all.js"
      data-auto-add-css="true"
    ></script>
  </head>
  <body></body>
</html>
<html>
  <head>
    <script
      src="https://example.com/fontawesome/js/all.js"
      data-auto-add-css="true"
    ></script>
  </head>
  <body></body>
</html>

You can also set configuration values to true by simply adding the attribute without a value.

<html>
  <head>
    <!-- Notice how the data-search-pseudo-elements has no explicit value. This sets it to "true". -->
    <script
      src="https://example.com/fontawesome/js/all.js"
      data-search-pseudo-elements
    ></script>
  </head>
  <body></body>
</html>

If you can’t add any attributes to a <script> tag you can create a configuration object. Make sure you do this before loading the Font Awesome scripts, like this:

<html>
  <head>
    <script>
      // The settings you provide will be merged with the default settings
      FontAwesomeConfig = {
        searchPseudoElements: true
      }
    </script>
    <script src="https://example.com/fontawesome/js/all.js"></script>
  </head>
  <body></body>
</html>

autoAddCss

Section titled “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 <head> of the DOM.

autoReplaceSvg

Section titled “autoReplaceSvg”

When true (default) this will cause Font Awesome to search through the DOM for any <i> tags and automatically replace them with <svg> tags.

<script
  src="https://example.com/fontawesome/js/all.js"
  data-auto-replace-svg
></script>

For example this <i> tag:

<i class="fas fa-kiwi-bird"></i>

Will be replaced with this <svg> tag:

<svg
  aria-hidden="true"
  data-prefix="fas"
  data-icon="kiwi-bird"
  role="img"
  viewBox="0 0 576 512"
  class="svg-inline--fa fa-kiwi-bird fa-w-18 fa-2x"
  data-fa-i2svg
>
  <path
    fill="currentColor"
    d="M575.81 217.98C572.64 157.41 518.28 112 457.63 112h-9.37c-52.82 0-104.25-16.25-147.74-46.24-41.99-28.96-96.04-41.62-153.21-28.7C129.3 41.12-.08 78.24 0 224c.04 70.95 38.68 132.8 95.99 166.01V464c0 8.84 7.16 16 16 16h16c8.84 0 16-7.16 16-16v-54.26c15.36 3.96 31.4 6.26 48 6.26 5.44 0 10.68-.73 16-1.18V464c0 8.84 7.16 16 16 16h16c8.84 0 16-7.16 16-16v-59.43c14.24-5.06 27.88-11.39 40.34-19.51C342.07 355.25 393.86 336 448.46 336c25.48 0 16.01-.31 23.05-.78l74.41 136.44c2.86 5.23 8.3 8.34 14.05 8.34 1.31 0 2.64-.16 3.95-.5 7.09-1.8 12.05-8.19 12.05-15.5 0 0 .14-240.24-.16-246.02zM463.97 248c-13.25 0-24-10.75-24-24 0-13.26 10.75-24 24-24s24 10.74 24 24c0 13.25-10.75 24-24 24zm80 153.25l-39.86-73.08c15.12-5.83 28.73-14.6 39.86-25.98v99.06z"
  ></path>
</svg>
<!-- <i class="fas fa-kiwi-bird"></i> -->

autoReplaceSvg through nesting

Section titled “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 <i> tag.

<script
  src="https://example.com/fontawesome/js/all.js"
  data-auto-replace-svg="nest"
></script>

This <i> tag:

<i class="fas fa-kiwi-bird"></i>

Will be nested within the existing tag:

<i data-fa-i2svg>
  <svg
    aria-hidden="true"
    data-prefix="fas"
    data-icon="kiwi-bird"
    role="img"
    viewBox="0 0 576 512"
    class="svg-inline--fa fa-kiwi-bird fa-w-18 fa-2x"
  >
    <path
      fill="currentColor"
      d="M575.81 217.98C572.64 157.41 518.28 112 457.63 112h-9.37c-52.82 0-104.25-16.25-147.74-46.24-41.99-28.96-96.04-41.62-153.21-28.7C129.3 41.12-.08 78.24 0 224c.04 70.95 38.68 132.8 95.99 166.01V464c0 8.84 7.16 16 16 16h16c8.84 0 16-7.16 16-16v-54.26c15.36 3.96 31.4 6.26 48 6.26 5.44 0 10.68-.73 16-1.18V464c0 8.84 7.16 16 16 16h16c8.84 0 16-7.16 16-16v-59.43c14.24-5.06 27.88-11.39 40.34-19.51C342.07 355.25 393.86 336 448.46 336c25.48 0 16.01-.31 23.05-.78l74.41 136.44c2.86 5.23 8.3 8.34 14.05 8.34 1.31 0 2.64-.16 3.95-.5 7.09-1.8 12.05-8.19 12.05-15.5 0 0 .14-240.24-.16-246.02zM463.97 248c-13.25 0-24-10.75-24-24 0-13.26 10.75-24 24-24s24 10.74 24 24c0 13.25-10.75 24-24 24zm80 153.25l-39.86-73.08c15.12-5.83 28.73-14.6 39.86-25.98v99.06z"
    ></path>
  </svg>
</i>

cssPrefix

Section titled “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.

<script
  src="https://example.com/fontawesome/js/all.js"
  data-family-prefix="icon"
></script>

To use the icon you would then use the following markup.

<i class="fas icon-kiwi-bird"></i>

familyDefault

Section titled “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:

config.familyDefault = 'sharp'

keepOriginalSource

Section titled “keepOriginalSource”

When using autoReplaceSvg or manually calling dom.i2svg() you have the option to retain the original <i> tag as a comment underneath the replacement <svg> tag. This is beneficial for debugging but does clutter the DOM a little.

<svg
  aria-hidden="true"
  data-prefix="fas"
  data-icon="kiwi-bird"
  role="img"
  viewBox="0 0 576 512"
  class="svg-inline--fa fa-kiwi-bird fa-w-18 fa-2x"
  data-fa-i2svg
>
  <path
    fill="currentColor"
    d="M575.81 217.98C572.64 157.41 518.28 112 457.63 112h-9.37c-52.82 0-104.25-16.25-147.74-46.24-41.99-28.96-96.04-41.62-153.21-28.7C129.3 41.12-.08 78.24 0 224c.04 70.95 38.68 132.8 95.99 166.01V464c0 8.84 7.16 16 16 16h16c8.84 0 16-7.16 16-16v-54.26c15.36 3.96 31.4 6.26 48 6.26 5.44 0 10.68-.73 16-1.18V464c0 8.84 7.16 16 16 16h16c8.84 0 16-7.16 16-16v-59.43c14.24-5.06 27.88-11.39 40.34-19.51C342.07 355.25 393.86 336 448.46 336c25.48 0 16.01-.31 23.05-.78l74.41 136.44c2.86 5.23 8.3 8.34 14.05 8.34 1.31 0 2.64-.16 3.95-.5 7.09-1.8 12.05-8.19 12.05-15.5 0 0 .14-240.24-.16-246.02zM463.97 248c-13.25 0-24-10.75-24-24 0-13.26 10.75-24 24-24s24 10.74 24 24c0 13.25-10.75 24-24 24zm80 153.25l-39.86-73.08c15.12-5.83 28.73-14.6 39.86-25.98v99.06z"
  ></path>
</svg>
<i class="fas fa-kiwi-bird"></i>

You can change the default value of keepOriginalSource to false:

<script
  src="https://example.com/fontawesome/js/all.js"
  data-keep-original-source="false"
></script>

Will prevent Font Awesome from adding the comment:

<svg
  aria-hidden="true"
  data-prefix="fas"
  data-icon="kiwi-bird"
  role="img"
  viewBox="0 0 576 512"
  class="svg-inline--fa fa-kiwi-bird fa-w-18 fa-2x"
  data-fa-i2svg
>
  <path
    fill="currentColor"
    d="M575.81 217.98C572.64 157.41 518.28 112 457.63 112h-9.37c-52.82 0-104.25-16.25-147.74-46.24-41.99-28.96-96.04-41.62-153.21-28.7C129.3 41.12-.08 78.24 0 224c.04 70.95 38.68 132.8 95.99 166.01V464c0 8.84 7.16 16 16 16h16c8.84 0 16-7.16 16-16v-54.26c15.36 3.96 31.4 6.26 48 6.26 5.44 0 10.68-.73 16-1.18V464c0 8.84 7.16 16 16 16h16c8.84 0 16-7.16 16-16v-59.43c14.24-5.06 27.88-11.39 40.34-19.51C342.07 355.25 393.86 336 448.46 336c25.48 0 16.01-.31 23.05-.78l74.41 136.44c2.86 5.23 8.3 8.34 14.05 8.34 1.31 0 2.64-.16 3.95-.5 7.09-1.8 12.05-8.19 12.05-15.5 0 0 .14-240.24-.16-246.02zM463.97 248c-13.25 0-24-10.75-24-24 0-13.26 10.75-24 24-24s24 10.74 24 24c0 13.25-10.75 24-24 24zm80 153.25l-39.86-73.08c15.12-5.83 28.73-14.6 39.86-25.98v99.06z"
  ></path>
</svg>

observeMutations

Section titled “observeMutations”

When your project first loads and you have enabled autoReplaceSvg, Font Awesome will search through your document for <i> 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 <i> 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 by setting observeMutations to true (default).

<script
  src="https://example.com/fontawesome/js/all.js"
  data-observe-mutations
></script>

mutateApproach

Section titled “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
  2. The necessary DOM changes are queued in a JavaScript array

The reason this happens in two steps is to reduce jank: 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.

<script
  src="https://example.com/fontawesome/js/all.js"
  data-mutate-approach="sync"
></script>

searchPseudoElements

Section titled “searchPseudoElements”

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
  2. A content property
<head>
  <script
    src="https://example.com/fontawesome/js/all.js"
    data-search-pseudo-elements
  ></script>
  <style>
    .glasses::before {
      display: none; /* Hide pseudo element as we'll inject an SVG */
      font: var(--fa-font-solid);
      content: '\f530';
    }
  </style>
</head>
<body>
  <span class="glasses"></span>
</body>

Make sure the font-family is set to a valid Font Awesome font, 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 <link> element loading the stylesheet, or enable searchPseudoElementsFullScan for a slower but more thorough approach.

searchPseudoElementsWarnings

Section titled “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

Section titled “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 can block its parsing.

Keep in mind that this option is significantly slower, especially for large documents.

showMissingIcons

Section titled “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:

<i class="fas fa-flaun-awesome"></i>

styleDefault

Section titled “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

config.styleDefault = 'fal'

Using the style name only

config.styleDefault = 'light'

Using the fa prefix with the style name

config.styleDefault = 'fa-light'