Add-ons

StorageArea.set()

Stores one or more items in the storage area, or update existing items.

When you store or update a value using this API, the storage.onChanged event will fire.

This is an asynchronous function that returns a Promise.

Syntax

let settingItem = browser.storage.<storageType>.set(
  keys             // object
)

<storageType> will be one of the writable storage types — storage.sync or storage.local.

Parameters

keys
An object containing one or more key/value pairs to be stored in storage. If an item already exists, its value will be updated.
  • Values of primitive types (number, string, boolean, null, undefined) will serialize (omitting any custom properties)
  • Dates, and Arrays, will serialize (omitting any custom properties)
  • In Firefox, RegExps, ArrayBuffers, Typed Arrays/Array Views (they make a copy of their buffer), Maps, and Set s will also serialize (omitting any custom properties)
  • Objects containing only the above types will serialize recursively, but will lose class information (and so prototypes) for all but the above types
  • Objects containing properties with unsupported types will be rejected with a DataCloneError (Firefox) or have each unsupported property replaced by the empty object (other implementations)
  • Unsupported types (Functions, SharedArrayBuffers, Promises, WeakSets, Errors, Proxys, etc) will be rejected with a DataCloneError (Firefox) or are accepted and silently replaced by the empty object (other implementations)

Return value

A Promise that will be fulfilled with no arguments if the operation succeeded. If the operation failed, the promise will be rejected with an error message.

Browser compatibility

ChromeEdgeFirefoxFirefox for AndroidOpera
Basic Support (Yes) (Yes)1454833

1. storage is limited to 1MB per value.

Examples

function onError(error) {
  console.log(`Error: ${error}`);
}

// Define two objects to store

// Note that the function will not be stored on any implementation
// and attempting to store it will throw an error in Firefox
let monster = {
  name: "Kraken",
  speak: function() {console.log("ROARR!!!")},
  birthday: new Date(2012, 11, 17)
}

// Without a function
let kitten = {
  name: "Moggy",
  birthday: new Date(2006, 7, 12)
}

// store the objects

// Works for all browsers
let setting = browser.storage.local.set({kitten});

// just check for errors
setting.then(null, onError);

// On Firefox:
//   "Error: DataCloneError: The object could not be cloned."
// Other implementations: both objects stored, but `speak === {}`
// for monster when retrieved.
setting = browser.storage.local.set({kitten, monster});

setting.then(null, onError);

Acknowledgements

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

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: cmcaine, wbamberg, jonathanKingston, Makyen, chrisdavidmills
 Last updated by: cmcaine,