Bug-1828220 add documentation and release notes for browser_action.onUserSettingsChanged event (#40488)

rebloor · github-actions[bot] · web-flow · commit 0bbc83440e89 · 2025-08-10T04:57:21.000+12:00
* Bug-1828220 add the browser_action.onUserSettingsChanged event * Addition event to action API * Apply linter suggestions Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Release note correction --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
diff --git a/files/en-us/mozilla/add-ons/webextensions/api/action/index.md b/files/en-us/mozilla/add-ons/webextensions/api/action/index.md
@@ -70,6 +70,8 @@ With the `action` API, you can:
 
 - {{WebExtAPIRef("action.onClicked")}}
   - : Fired when a browser action icon is clicked. This event will not fire if the browser action has a popup.
+- {{WebExtAPIRef("action.onUserSettingsChanged")}}
+  - : Fired when a change occurs in the user-specified settings that affect an extension's action.
 
 {{WebExtExamples("h2")}}
 
diff --git a/files/en-us/mozilla/add-ons/webextensions/api/action/onusersettingschanged/index.md b/files/en-us/mozilla/add-ons/webextensions/api/action/onusersettingschanged/index.md
@@ -0,0 +1,43 @@
+---
+title: action.onUserSettingsChanged
+slug: Mozilla/Add-ons/WebExtensions/API/action/onUserSettingsChanged
+page-type: webextension-api-event
+browser-compat: webextensions.api.action.onUserSettingsChanged
+sidebar: addonsidebar
+---
+
+Fired when a change occurs in the user-specified settings that affect an extension's action.
+
+## Syntax
+
+```js-nolint
+browser.action.onUserSettingsChanged.addListener(listener)
+browser.action.onUserSettingsChanged.removeListener(listener)
+browser.action.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 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}}
diff --git a/files/en-us/mozilla/add-ons/webextensions/api/browseraction/index.md b/files/en-us/mozilla/add-ons/webextensions/api/browseraction/index.md
@@ -67,6 +67,8 @@ 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")}}
 
diff --git a/files/en-us/mozilla/add-ons/webextensions/api/browseraction/onusersettingschanged/index.md b/files/en-us/mozilla/add-ons/webextensions/api/browseraction/onusersettingschanged/index.md
@@ -0,0 +1,43 @@
+---
+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}}
diff --git a/files/en-us/mozilla/firefox/releases/142/index.md b/files/en-us/mozilla/firefox/releases/142/index.md
@@ -77,6 +77,7 @@ Firefox 142 is the current [Beta version of Firefox](https://www.firefox.com/en-
 ## 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")}} and {{WebExtAPIRef("action.onUserSettingsChanged")}} events that listen for changes in the user-specified settings that affect an extension's action. ([Firefox bug 1828220](https://bugzil.la/1828220))
 
 <!-- ### Removals -->
 
