index.md

title	slug	page-type	browser-compat
storage.onChanged	Mozilla/Add-ons/WebExtensions/API/storage/onChanged	webextension-api-event	webextensions.api.storage.onChanged

{{AddonSidebar}}

Fired when {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}}, {{WebExtAPIRef('storage.StorageArea.remove','storageArea.remove')}}, or {{WebExtAPIRef('storage.StorageArea.clear','storageArea.clear')}} executes against a storage area, returning details of only changed keys. A callback is called only when there are changes to the underlying data.

Note: In Firefox, the information returned includes all keys within the storage area {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}} ran against whether they changed or not. Also, a callback may be invoked when there is no change to the underlying data. Details of the changed items are found by examining each returned key's {{WebExtAPIRef('storage.StorageChange')}} object. See Firefox bug 1833153.

Syntax

browser.storage.onChanged.addListener(listener)
browser.storage.onChanged.removeListener(listener)
browser.storage.onChanged.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:

    • changes
      • : object. Object describing the change. The name of each property is the name of each key. The value of each key is a {{WebExtAPIRef('storage.StorageChange')}} object describing the change to that item.
    • areaName
      • : string. The name of the storage area ("sync", "local", or "managed") to which the changes were made.

Browser compatibility

{{Compat}}

Examples

/*
Log the storage area that changed,
then for each item changed,
log its old value and its new value.
*/
function logStorageChange(changes, area) {
  console.log(`Change in storage area: ${area}`);

  const changedItems = Object.keys(changes);

  for (const item of changedItems) {
    console.log(`${item} has changed:`);
    console.log("Old value: ", changes[item].oldValue);
    console.log("New value: ", changes[item].newValue);
  }
}

browser.storage.onChanged.addListener(logStorageChange);

{{WebExtExamples}}

Note: This API is based on Chromium's chrome.storage API. This documentation is derived from storage.json in the Chromium code.