Google Chrome Extensions

chrome.storage

Use the chrome.storage module to store, retrieve, and track changes to user data. This API has been optimized to meet the specific storage needs of extensions. It provides the same storage capabilities as the localStorage API with the following key differences:

Manifest

You must declare the "storage" permission in the extension manifest to use the storage API. For example:

{
  "name": "My extension",
  ...
  "permissions": [
    "storage"
  ],
  ...
}

Usage

To store user data for your extension, you can use either storage.sync or storage.local. When using storage.sync, the stored data will automatically be synced to any Chrome browser that the user is logged into, provided the user has sync enabled.

When Chrome is offline, Chrome stores the data locally. The next time the browser is online, Chrome syncs the data. Even if a user disables syncing, storage.sync will still work. In this case, it will behave identically to storage.local.

Confidential user information should not be stored! The storage area isn't encrypted.

Storage and throttling limits

chrome.storage is not a big truck. It's a series of tubes. And if you don't understand, those tubes can be filled, and if they are filled when you put your message in, it gets in line, and it's going to be delayed by anyone that puts into that tube enormous amounts of material.

For details on the current limits of the storage API, and what happens when those limits are exceeded, please see the API reference.

Examples

The following example checks for CSS code saved by a user on a form, and if found, stores it.

function saveChanges() {
  // Get a value saved in a form.
  var theValue = textarea.value;
  // Check that there's some code there.
  if (!theValue) {
    message('Error: No value specified');
    return;
  }
  // Save it using the Chrome extension storage API.
  chrome.storage.sync.set({'value': theValue}, function() {
    // Notify that we saved.
    message('Settings saved');
  });
}

If you're interested in tracking changes made to a data object, you can add a listener to its onChanged event. Whenever anything changes in storage, that event fires. Here's sample code to listen for saved changes:

chrome.storage.onChanged.addListener(function(changes, namespace) {
  for (key in changes) {
    var storageChange = changes[key];
    console.log('Storage key "%s" in namespace "%s" changed. ' +
                'Old value was "%s", new value is "%s".',
                key,
                namespace,
                storageChange.oldValue,
                storageChange.newValue);
  }
});

You can find examples that use this API on the Samples page.

API Reference: chrome.storage

Types

StorageChange

( object )

Properties of StorageChange

oldValue ( optional any )
The old value of the item, if there was an old value.
newValue ( optional any )
The new value of the item, if there is a new value.

StorageArea

( object )

Methods of StorageArea

get

StorageArea.get(array of string or string or object keys)

Gets one or more items from storage.

Parameters

keys ( optional array of string or string or object )
A single key to get, list of keys to get, or a dictionary specifying default values (see description of the object). An empty list or object will return an empty result object. Pass in null to get the entire contents of storage.

Callback function

The callback parameter should specify a function that looks like this:

function(object items) {...};
items ( object )
Object with items in their key-value mappings.

getBytesInUse

StorageArea.getBytesInUse(array of string or string keys)

Gets the amount of space (in bytes) being used by one or more items.

Parameters

keys ( optional array of string or string )
A single key or list of keys to get the total usage for. An empty list will return 0. Pass in null to get the total usage of all of storage.

Callback function

The callback parameter should specify a function that looks like this:

function(integer bytesInUse) {...};
bytesInUse ( integer )
Amount of space being used in storage, in bytes.

set

StorageArea.set(object items)

Sets multiple items.

Parameters

items ( object )
Object specifying items to augment storage with. Values that cannot be serialized (functions, etc) will be ignored.

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function() {...};

remove

StorageArea.remove(array of string or string keys)

Removes one or more items from storage.

Parameters

keys ( array of string or string )
A single key or a list of keys for items to remove.

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function() {...};

clear

StorageArea.clear()

Removes all items from storage.

Properties

sync

chrome.storage.sync
sync ( StorageArea )
Items under the "sync" storage area are synced using Chrome Sync.

Properties of sync

QUOTA_BYTES ( 102,400 )
The maximum total amount (in bytes) of data that can be stored in sync storage, as measured by the JSON stringification of every value plus every key's length. Updates that would cause this limit to be exceeded fail immediately and set chrome.runtime.lastError.
QUOTA_BYTES_PER_ITEM ( 4,096 )
The maximum size (in bytes) of each individual item in sync storage, as measured by the JSON stringification of its value plus its key length. Updates containing items larger than this limit will fail immediately and set chrome.runtime.lastError.
MAX_ITEMS ( 512 )
The maximum number of items that can be stored in sync storage. Updates that would cause this limit to be exceeded will fail immediately and set chrome.runtime.lastError.
MAX_WRITE_OPERATIONS_PER_HOUR ( 1,000 )
The maximum number of set, remove, or clear operations that can be performed each hour. Updates that would cause this limit to be exceeded fail immediately and set chrome.runtime.lastError.
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE ( 10 )
The maximum number of set, remove, or clear operations that can be performed each minute, sustained over 10 minutes. Updates that would cause this limit to be exceeded fail immediately and set chrome.runtime.lastError.

local

chrome.storage.local
local ( StorageArea )
Items under the "local" storage area are local to each machine.

Properties of local

QUOTA_BYTES ( 5,242,880 )
The maximum amount (in bytes) of data that can be stored in local storage, as measured by the JSON stringification of every value plus every key's length. This value will be ignored if the extension has the unlimitedStorage permission. Updates that would cause this limit to be exceeded fail immediately and set chrome.runtime.lastError.

Events

onChanged

chrome.storage.onChanged.addListener(function(object changes, string areaName) {...});

Fired when one or more items change.

Listener Parameters

changes ( object )
Object mapping each key that changed to its corresponding StorageChange for that item.
areaName ( string )
The name of the storage area ("sync" or "local") the changes are for.

Sample Extensions that use chrome.storage

  • Stylizr – Spruce up your pages with custom CSS.
  • WebNavigation Tech Demo – Demonstration of the WebNavigation extension API.