Insert the supporting CSS into the <head> 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 <svg> tags replacements. All replacements will have this class.
searchPseudoElements
false
Searches for elements with a Font Awesome CSS family-name and content property and replaces with inline SVG
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
Advertisement
Remove ads with a Pro plan!
A subscription to a Pro-level plan will remove all third-party advertisements on fontawesome.com.
And of course Pro-level plans come with…
All 26,233 icons in Font Awesome
5 Classic styles of every icon
3 Sharp styles of every icon
A Perpetual License to use Pro
Services and tools to make easy work of using icons
You can also set configuration values to true by simply adding the attribute without a value.
<head><!-- Notice how the data-search-pseudo-elements has no explicit value. This sets it to "true". --><scriptsrc="https://example.com/fontawesome/vVERSION/js/all.js"data-search-pseudo-elements></script></head><body></body>
If you can't add any attributes to a <script> tag you can set the configuration like this:
<head><script><!-- The settings you provide will be merged with the default settings -->
FontAwesomeConfig ={searchPseudoElements:true}</script><scriptsrc="https://example.com/fontawesome/vVERSION/js/all.js"></script></head><body></body>
autoAddCss
Advertisement
Remove ads with a Pro plan!
A subscription to a Pro-level plan will remove all third-party advertisements on fontawesome.com.
And of course Pro-level plans come with…
All 26,233 icons in Font Awesome
5 Classic styles of every icon
3 Sharp styles of every icon
A Perpetual License to use Pro
Services and tools to make easy work of using icons
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
When true (default) this will cause Font Awesome to search through the DOM for any <i> tags and automatically replace them with <svg> tags.
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.
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
Advertisement
Remove ads with a Pro plan!
A subscription to a Pro-level plan will remove all third-party advertisements on fontawesome.com.
And of course Pro-level plans come with…
All 26,233 icons in Font Awesome
5 Classic styles of every icon
3 Sharp styles of every icon
A Perpetual License to use Pro
Services and tools to make easy work of using icons
To use the icon you would then use the following markup.
<iclass="fas icon-kiwi-bird"></i>
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:
config.familyDefault ='sharp'
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.
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(opens new window) by setting observeMutations to true (default).
Keep in mind that version 10 of IE does not support the MutationObserver object.
mutateApproach
Replacing icons with SVG actually happens in two steps:
Icons are parsed to pull out information such as icon name, family, style, and any additional stuff like Power Transforms
The necessary DOM changes are queued in a JavaScript array
The reason this happens in two steps is to reduce
jank(opens new window):
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.
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 DOM for any elements that have:
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:
<iclass="fas fa-flaun-awesome"></i>
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'
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.