We're looking for a person or people to help audit MDN to find places we could speed up. Is this you or someone you know? Check out the RFP: https://mzl.la/2IHcMiE

Use BrowserSetting.set() to change the browser setting to a new value.

There are some rules that can restrict when extensions are able to change settings:

  • some settings are locked, so they can't be changed by extensions at all
  • if multiple extensions try to modify the same setting, then extensions are given a precedence ordering based on when they were installed. More-recently installed extensions have precedence over less-recently installed extension.

This means that if extension X tries to change a setting:

  1. If the setting is locked, then the setting is not changed. However, X's change is remembered, and it is stored in a queue, ordered by X's precedence relative to any other extensions that tried to change the setting. If the setting becomes unlocked later on, the first extension in the queue gets to change the setting.
  2. Otherwise, if no other extension has already changed the setting, then X succeeds in changing the setting, and is then said to "control" the setting.
  3. Otherwise, if a lower-precedence extension Y has already changed the setting, then X succeeds in changing the setting, and now controls the setting. However, Y's change is remembered, and is stored in a queue in precedence order. If X subsequently clears its value, or if X is disabled or uninstalled,  the first extension in the queue gets to make its change to the setting.
  4. Otherwise, if a higher-precedence extension Z has already changed the setting, then X does not succeed in changing the setting, but its change is queued. If Z subsequently clears its value, or if Z is disabled or uninstalled, the first extension in the queue gets to make its change to the setting.

An extension can find out which of these scenarios applies by examining the "levelOfControl" property returned from a call to BrowserSetting.get().

The BrowserSetting.set() method returns a Promise that resolves to a boolean: if an attempt to change a setting actually results in the setting being changed (scenarios 2 and 3 above) the boolean is true: otherwise it is false.


var setting = setting.set(
  details     // object


An object that must contain the following property:
any. The value you want to change the setting to. Its type depends on the particular setting.

Return value

A Promise that will be fulfilled with a boolean: true if the setting was modified, false otherwise (for example, because the extension did not control the setting).

Browser compatibility

See types.BrowserSetting.


Modify the hyperlinkAuditingEnabled setting:

function onSet(result) {
  if (result) {
    console.log("Value was updated");
  } else {
    console.log("Value was not updated");

browser.browserAction.onClicked.addListener(() => {

    var setting = browser.privacy.websites.hyperlinkAuditingEnabled.set({
      value: false



This API is based on Chromium's chrome.types API.

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.

Document Tags and Contributors

 Contributors to this page: andrewtruongmoz, wbamberg, jwhitlock
 Last updated by: andrewtruongmoz,