how-to-guide

How to Configure Font Awesome 7: Data Attributes vs JavaScript Config Object

March 1, 2026 FortAwesome/Font-Awesome ↗

Configure Font Awesome 7 before the library loads by either adding data attributes to the <script> tag or defining a window.FontAwesomeConfig object, with both methods merging into the internal config proxy exposed at runtime.

Font Awesome 7, maintained in the FortAwesome/Font-Awesome repository, offers two complementary initialization patterns that determine how icons render, how CSS injects, and how the library observes DOM mutations. Understanding the precise merge logic in js/fontawesome.js ensures your configuration takes precedence without conflicts.

Understanding Font Awesome 7 Configuration Architecture

The configuration system resides in js/fontawesome.js and operates in three distinct phases:

Attribute extraction (lines 1166–1176): The loader scans the first <script> element carrying Font Awesome attributes and coerces them into an initial object.
Global config merge (lines 1178–1199): The library merges window.FontAwesomeConfig (if present) with internal defaults (_default) using a spread operation.
Proxy exposure (lines 1200–1215): A config proxy exposes the final settings and triggers callbacks when values change at runtime.

Configuring Font Awesome 7 with Data Attributes

Data attributes provide a declarative, HTML-only method to set configuration keys before the script executes.

Supported Data Attributes

The attrs array in js/fontawesome.js maps specific data attributes to internal config keys:

Data attribute	Config key	Default value
`data-family-prefix`	`familyPrefix`	(deprecated)
`data-css-prefix`	`cssPrefix`	`"fa"`
`data-family-default`	`familyDefault`	`"classic"`
`data-style-default`	`styleDefault`	`"solid"`
`data-replacement-class`	`replacementClass`	`"svg-inline--fa"`
`data-auto-replace-svg`	`autoReplaceSvg`	`true`
`data-auto-add-css`	`autoAddCss`	`true`
`data-search-pseudo-elements`	`searchPseudoElements`	`false`
`data-search-pseudo-elements-warnings`	`searchPseudoElementsWarnings`	`true`
`data-search-pseudo-elements-full-scan`	`searchPseudoElementsFullScan`	`false`
`data-observe-mutations`	`observeMutations`	`true`
`data-mutate-approach`	`mutateApproach`	`"async"`
`data-keep-original-source`	`keepOriginalSource`	`true`
`data-measure-performance`	`measurePerformance`	`false`
`data-show-missing-icons`	`showMissingIcons`	`true`

Empty string values are coerced to true, while explicit 'false' strings coerce to boolean false.

Implementation Example

Add configuration directly to the Font Awesome script tag:

<!DOCTYPE html>
<html>
<head>
  <script 
    src="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.2.0/js/all.min.js"
    data-auto-replace-svg="false"
    data-auto-add-css="true"
    data-style-default="regular"
    data-search-pseudo-elements="true">
  </script>
</head>
<body>
  <i class="fa-solid fa-heart"></i>
  <!-- Icon will NOT auto-replace because data-auto-replace-svg is false -->
</body>
</html>

The getAttrConfig function in js/fontawesome.js processes these attributes during the initial load phase.

Configuring Font Awesome 7 with JavaScript Config Object

For dynamic or conditional configuration, define window.FontAwesomeConfig before the library script executes.

Setting window.FontAwesomeConfig

Define the global configuration object in a preceding script block:

<!DOCTYPE html>
<html>
<head>
  <script>
    window.FontAwesomeConfig = {
      autoReplaceSvg: true,
      autoAddCss: false,          // Prevent automatic CSS injection
      styleDefault: 'light',
      keepOriginalSource: false,  // Remove original <i> elements after replacement
      showMissingIcons: false     // Suppress console warnings for missing icons
    };
  </script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.2.0/js/all.min.js"></script>
</head>
<body>
  <i class="fa-solid fa-star"></i>
</body>
</html>

According to the source code in js/fontawesome.js lines 1178–1199, the library merges window.FontAwesomeConfig with the internal _default object using the spread operator ..._default, ...initial, where initial represents the global config.

Runtime Configuration Updates

After Font Awesome 7 loads, the config object becomes a reactive proxy. You can modify settings dynamically, and the library adjusts behavior immediately:

// Access the config object after Font Awesome is loaded
FontAwesome.config.autoAddCss = true;          // Enable CSS injection retroactively
FontAwesome.config.showMissingIcons = false;   // Silence missing icon warnings
FontAwesome.config.observeMutations = false;   // Disable DOM observer

The proxy implementation in js/fontawesome.js lines 1200–1215 ensures that setters trigger internal callbacks, updating the processing pipeline without requiring a page reload.

Configuration Precedence and Merge Logic

When both data attributes and window.FontAwesomeConfig are present, Font Awesome 7 applies the following merge strategy:

Internal defaults (_default object) provide the base layer.
Data attributes on the script tag are parsed and stored in initial.
Global config (window.FontAwesomeConfig) is also merged into initial.
Final spread: The config object becomes { ..._default, ...initial }, meaning explicit settings override defaults.

If the same key is defined in both data attributes and the JavaScript config object, the last one processed in the merge chain takes precedence. Since window.FontAwesomeConfig is merged after attribute extraction in the initialization flow, JavaScript values typically override data attributes when conflicts occur.

Summary

Data attributes provide declarative configuration directly on the <script> tag, parsed by getAttrConfig in js/fontawesome.js lines 1166–1176.
JavaScript config uses window.FontAwesomeConfig defined before the library loads, merged with defaults in lines 1178–1199.
Runtime updates are supported via the config proxy (lines 1200–1215), allowing dynamic behavior changes without reload.
Both methods support identical configuration keys, including autoReplaceSvg, autoAddCss, styleDefault, and observeMutations.
Configuration follows a merge precedence: defaults ← data attributes ← window.FontAwesomeConfig.

Frequently Asked Questions

Can I use both data attributes and JavaScript config together?

Yes. Font Awesome 7 supports hybrid configuration. Define window.FontAwesomeConfig for complex logic or dynamic values, and use data attributes for simple boolean flags. The library merges both sources into the internal initial object before applying defaults, with JavaScript values typically taking precedence over data attributes when the same key is defined in both.

Why is my Font Awesome 7 configuration not working?

Configuration must be defined before the Font Awesome script executes. If using data attributes, ensure they are on the actual <script> tag that loads the library, not a separate tag. For JavaScript config, place the window.FontAwesomeConfig assignment in a <script> block that appears earlier in the DOM than the Font Awesome loader. Check browser DevTools to verify that window.FontAwesomeConfig exists before the library initializes.

How do I change Font Awesome 7 settings after the page has loaded?

After initialization, access the global FontAwesome.config object (or the config export if using modules). This object is a reactive proxy; modifying properties like config.autoReplaceSvg or config.observeMutations immediately updates the library’s internal state and triggers any registered change callbacks. This allows you to enable CSS injection, toggle mutation observers, or change default styles dynamically without reloading the page.

What is the default style in Font Awesome 7 if not specified?

If neither data-style-default nor window.FontAwesomeConfig.styleDefault is defined, Font Awesome 7 defaults to "solid" as specified in the _default object within js/fontawesome.js. Similarly, the default family is "classic" unless overridden via data-family-default or the config object. These defaults determine which icon variant renders when you use generic class names like fa-user without specifying a style prefix.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}

Ask your agent:

"Use Instagit MCP to understand how FortAwesome/Font-Awesome works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →