It's asynchronous with bulk read and write operations, and therefore
faster than the blocking and serial localStorage API.

User data can be stored as objects
(the localStorage API stores data in strings).

Enterprise policies configured by the administrator for the extension
can be read (using storage.managed with a
schema).

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 app,
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.

The storage.managed storage is read-only.

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 quota information for
sync and local.

Examples

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

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:

Types

StorageChange

StorageArea

methods

get

StorageArea.get(string or array of string or object keys, function callback)

Gets one or more items from storage.

Parameters

string or array of string or object

(optional)
keys

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.

function

callback

Callback with storage items, or on failure (in which case runtime.lastError will be set).

getBytesInUse

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.

function

callback

Callback with the amount of space being used by storage, or on failure (in which case runtime.lastError will be set).

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

function(integer bytesInUse) {...};

integer

bytesInUse

Amount of space being used in storage, in bytes.

set

StorageArea.set(object items, function callback)

Sets multiple items.

Parameters

object

items

An object which gives each key/value pair to update storage with. Any other key/value pairs in storage will not be affected.

Primitive values such as numbers will serialize as expected. Values with a typeof"object" and "function" will typically serialize to {}, with the exception of Array (serializes as expected), Date, and Regex (serialize using their String representation).

Properties

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 runtime.lastError.

8,192

QUOTA_BYTES_PER_ITEM

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 runtime.lastError.

512

MAX_ITEMS

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 runtime.lastError.

1,800

MAX_WRITE_OPERATIONS_PER_HOUR

The maximum number of set, remove, or clear operations that can be performed each hour. This is 1 every 2 seconds, a lower ceiling than the short term higher writes-per-minute limit.

Updates that would cause this limit to be exceeded fail immediately and set runtime.lastError.

120

MAX_WRITE_OPERATIONS_PER_MINUTE

Since Chrome 40.

The maximum number of set, remove, or clear operations that can be performed each minute. This is 2 per second, providing higher throughput than writes-per-hour over a shorter period of time.

Updates that would cause this limit to be exceeded fail immediately and set runtime.lastError.

1,000,000

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Deprecated since Chrome 40.
The storage.sync API no longer has a sustained write operation quota.

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 runtime.lastError.