Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the BSD License.
©2012 Google
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:
storage.sync).localStorage API stores data in strings).You must declare the "storage" permission in the extension manifest to use the storage API. For example:
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
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.
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.
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.
Gets one or more items from storage.
The callback parameter should specify a function that looks like this:
function(object items) {...};Gets the amount of space (in bytes) being used by one or more items.
The callback parameter should specify a function that looks like this:
function(integer bytesInUse) {...};Removes all items from storage.
102,400
)
4,096
)
512
)
1,000
)
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.
10
)
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.
5,242,880
)
unlimitedStorage permission. Updates that would cause this limit to be exceeded fail immediately and set chrome.runtime.lastError.
Fired when one or more items change.