# Font Awesome 7 Configuration Callbacks: How to Use onChange Hooks

> Learn how to use Font Awesome 7 configuration callbacks with onChange hooks. Register callbacks for runtime changes and get an unsubscribe function for cleanup.

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

---

**Font Awesome 7 exposes a global `FontAwesomeConfig` object with an `onChange` method that lets you register callbacks to react to any configuration change at runtime, returning an unsubscribe function for cleanup.**

Font Awesome 7 introduces a powerful observer pattern for its runtime configuration, allowing developers to hook into configuration changes dynamically. The library maintains an internal callback registry that fires whenever properties like `autoAddCss` or `cssPrefix` are modified through the global `FontAwesomeConfig` object. Understanding these Font Awesome 7 configuration callbacks enables you to build reactive integrations that respond to live updates in both browser and NPM package environments.

## How the onChange Mechanism Works Internally

Font Awesome 7 implements a reactive configuration system using a private state object wrapped in a proxy-like layer. The core logic resides in [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js) for the browser bundle and is mirrored in `js-packages/@fortawesome/fontawesome-svg-core/index.js` for module consumers.

### The Configuration Proxy and Private State

The library stores actual configuration values in a private variable named **`_config`**, which is created by merging default settings with user-provided initial values:

```javascript
var _config = _objectSpread2(_objectSpread2({}, _default), initial);

```

The public `FontAwesomeConfig` object acts as a proxy. Every configurable property is defined using `Object.defineProperty` with custom getters and setters. When you read a property, it returns the value from `_config`. When you write a property, it updates `_config` and immediately notifies all registered listeners.

The library maintains an internal array called **`_onChangeCb`** to store registered callbacks:

```javascript
var _onChangeCb = [];

```

According to the source code in [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js) (lines 1207‑1209), every setter invocation iterates over this array and passes the updated configuration object to each callback:

```javascript
_onChangeCb.forEach(cb => cb(config));

```

### The onChange Registration Function

The **`onChange(cb)`** method is exposed directly on the `FontAwesomeConfig` object. When called, it pushes your callback onto the `_onChangeCb` array and returns a cleanup function. The implementation in [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js) (lines 1232‑1236) looks like this:

```javascript
function onChange(cb) {
  _onChangeCb.push(cb);
  return function() {
    _onChangeCb = _onChangeCb.filter(c => c !== cb);
  };
}

```

This pattern allows you to subscribe to changes and later unsubscribe to prevent memory leaks.

## Implementing Font Awesome 7 Configuration Callbacks

### Registering an onChange Hook

To start listening for configuration changes, call `FontAwesomeConfig.onChange()` after the Font Awesome script loads. The callback receives the entire updated configuration object:

```javascript
const unsubscribe = FontAwesomeConfig.onChange((newConfig) => {
  console.log('Font Awesome config changed:', newConfig);
  
  // React to specific changes by inspecting the config
  if (!newConfig.autoAddCss) {
    console.warn('Automatic CSS injection disabled – manual CSS loading required.');
  }
});

```

### Understanding Callback Arguments

Callbacks receive the **complete `config` object**, not just the changed property. The library does not diff the changes or tell you which specific key was altered; it simply notifies you that the configuration state has updated. Your callback must inspect the properties it cares about:

```javascript
FontAwesomeConfig.onChange((cfg) => {
  console.log(`Current CSS prefix: ${cfg.cssPrefix}`);
  console.log(`Auto-add CSS enabled: ${cfg.autoAddCss}`);
});

```

### Cleaning Up Callbacks

The function returned by `onChange` removes the callback from the internal `_onChangeCb` array. Call it when your component unmounts or you no longer need updates:

```javascript
// Later, when cleaning up
unsubscribe();  // Removes the callback from _onChangeCb

```

## Real-World Usage: Dynamic CSS Handling

A practical use case involves reacting to the `cssPrefix` change to swap stylesheets dynamically. Because the callback fires whenever any property changes, you can inspect the new prefix and load corresponding custom CSS:

```javascript
FontAwesomeConfig.onChange((cfg) => {
  if (cfg.cssPrefix !== 'fa') {
    // Remove the default stylesheet
    const oldLink = document.querySelector('link[data-fa]');
    if (oldLink) oldLink.remove();

    // Inject custom stylesheet based on the new prefix
    const link = document.createElement('link');
    link.rel = 'stylesheet';
    link.href = `/my-icons/${cfg.cssPrefix}.css`;
    link.dataset.fa = '';
    document.head.appendChild(link);
  }
});

```

Triggering this callback is as simple as updating a configuration property:

```javascript
FontAwesomeConfig.autoAddCss = false;   // Fires all registered callbacks
FontAwesomeConfig.cssPrefix = 'fab';    // Fires callbacks again

```

## Source Code Locations

The Font Awesome 7 configuration callback system is implemented consistently across the browser bundle and NPM packages:

| File | Role | Key Lines |
|------|------|-----------|
| [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js) | Core browser bundle; defines `FontAwesomeConfig`, `_onChangeCb`, and the setter invocation logic. | 1207‑1209 (setter), 1232‑1236 (`onChange`) |
| `js-packages/@fortawesome/fontawesome-svg-core/index.js` | NPM package version for module bundlers; mirrors the callback mechanism. | 1209‑1212 (setter), 1235‑1240 (`onChange`) |
| [`js/all.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/all.js) | Full icon bundle including the same configuration proxy logic. | Throughout configuration initialization section |

These files collectively provide the **onChange hook** that developers can leverage to keep their UI in sync with Font Awesome’s runtime configuration.

## Summary

- **Font Awesome 7** exposes configuration callbacks through the global `FontAwesomeConfig.onChange()` method.
- The library maintains an internal **`_onChangeCb`** array that stores all registered callbacks.
- Every configuration property setter iterates over `_onChangeCb` and invokes each listener with the updated config object.
- The `onChange()` method returns an **unsubscribe function** that removes the callback from the internal registry to prevent memory leaks.
- This mechanism works identically in both the browser bundle ([`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js)) and the NPM package (`@fortawesome/fontawesome-svg-core`).

## Frequently Asked Questions

### How do I register a callback to listen for Font Awesome 7 configuration changes?

Call `FontAwesomeConfig.onChange()` and pass a function that accepts the configuration object. This works immediately after the Font Awesome script loads in the browser or after importing the config object from the NPM package.

### What information does the onChange callback receive?

The callback receives the **entire updated `config` object** containing all current settings. The library does not tell you which specific property changed; you must compare values against previous states inside your callback if you need to detect specific changes.

### How do I stop listening to configuration updates?

Store the return value from `onChange()` (which is a function) and call it when you want to unsubscribe. This removes your callback from the internal `_onChangeCb` array, preventing further invocations and potential memory leaks.

### Does the onChange hook work with the NPM package (@fortawesome/fontawesome-svg-core)?

Yes. The same `onChange` mechanism is implemented in `js-packages/@fortawesome/fontawesome-svg-core/index.js` (lines 1235‑1240), allowing module-based applications to react to configuration changes just like browser-based implementations.