Font Awesome 7 Configuration Callbacks: How to Use onChange Hooks

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 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:

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:

var _onChangeCb = [];

According to the source code in js/fontawesome.js (lines 1207‑1209), every setter invocation iterates over this array and passes the updated configuration object to each callback:

_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 (lines 1232‑1236) looks like this:

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:

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:

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:

// 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:

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:

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	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	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) 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.

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