mdn · rebloor · Aug 9, 2025 · Jul 21, 2025 · Jul 23, 2025 · Jul 23, 2025
@@ -67,6 +67,9 @@ With the `browserAction` API, you can:
 
 - {{WebExtAPIRef("browserAction.onClicked")}}
   - : Fired when a browser action icon is clicked. This event will not fire if the browser action has a popup.
+- {{WebExtAPIRef("browserAction.onUserSettingsChanged")}}
+  - : Fired when a change occurs in the user-specified settings that affect an extension's browser action.
+
 
 {{WebExtExamples("h2")}}
 

@@ -0,0 +1,44 @@
+---
+title: browserAction.onUserSettingsChanged
+slug: Mozilla/Add-ons/WebExtensions/API/browserAction/onUserSettingsChanged
+page-type: webextension-api-event
+browser-compat: webextensions.api.browserAction.onUserSettingsChanged
+sidebar: addonsidebar
+---
+
+Fired when a change occurs in the user-specified settings that affect an extension's browser action.
+
+## Syntax
+
+```js-nolint
+browser.browserAction.onUserSettingsChanged.addListener(listener)
+browser.browserAction.onUserSettingsChanged.removeListener(listener)
+browser.browserAction.onUserSettingsChanged.hasListener(listener)
+```
+
+Events have three functions:
+
+- `addListener(listener)`
+  - : Adds a listener to this event.
+- `removeListener(listener)`
+  - : Stop listening to this event. The `listener` argument is the listener to remove.
+- `hasListener(listener)`
+  - : Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.
+
+## addListener syntax
+
+### Parameters
+
+- `listener`
+  - : The function called when this event occurs. The function is passed these arguments:
+    - `change`
+      - : 'object'. Details of the changed user-specified settings. 
+        - `isOnToolbar`
+          - : `boolean`. Whether the extension's browser action icon is visible on the top-level toolbar of the browser windows (i.e., whether the extension has been 'pinned' by the user).
+
+
+{{WebExtExamples}}
+
+## Browser compatibility
+
+{{Compat}}
@@ -71,6 +71,7 @@ Firefox 142 is the current [Nightly version of Firefox](https://www.firefox.com/
 ## Changes for add-on developers
 
 - Cookies created with {{WebExtAPIRef("cookies.set()")}} in Nightly are now validated, and invalid cookies are rejected. The implementation in Nightly is to enable monitoring for any issues. The intention is to enforce validation in all channels in a future release. ([Firefox bug 1976197](https://bugzil.la/1976197))
+- Adds the {{WebExtAPIRef("browserAction.onUserSettingsChanged")}} event that listens for changes in the user-specified settings that affect an extension's browser action. ([Firefox bug 1828220](https://bugzil.la/1828220))
 
 <!-- ### Removals -->