set()

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.

Syntax

js
let setting = setting.set(
  details     // object
)

Parameters

details

An object that must contain the following property:

value

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.

Example

Modify the hyperlinkAuditingEnabled setting (this requires the "privacy" permission):

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

browser.browserAction.onClicked.addListener(() => {
  let setting = browser.privacy.websites.hyperlinkAuditingEnabled.set({
    value: false,
  });
  setting.then(onSet);
});

Note:

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