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

> Learn to configure Font Awesome 7 using data attributes or a JavaScript config object. Discover how both methods merge into the internal config proxy for dynamic access.

- Repository: [Font Awesome/Font-Awesome](https://github.com/FortAwesome/Font-Awesome)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js) ensures your configuration takes precedence without conflicts.

## Understanding Font Awesome 7 Configuration Architecture

The configuration system resides in [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js) and operates in three distinct phases:

1. **Attribute extraction** (lines 1166–1176): The loader scans the first `<script>` element carrying Font Awesome attributes and coerces them into an `initial` object.
2. **Global config merge** (lines 1178–1199): The library merges `window.FontAwesomeConfig` (if present) with internal defaults (`_default`) using a spread operation.
3. **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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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:

```html
<!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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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:

```html
<!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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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:

```javascript
// 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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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:

1. **Internal defaults** (`_default` object) provide the base layer.
2. **Data attributes** on the script tag are parsed and stored in `initial`.
3. **Global config** (`window.FontAwesomeConfig`) is also merged into `initial`.
4. **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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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.