<h2 id="overview">Overview</h2>

<p>
This API has been optimized
to meet the specific storage needs of extensions.
It provides the same storage capabilities as the
<a href="https://developer.mozilla.org/en/DOM/Storage#localStorage">localStorage API</a>
with the following key differences:
</p>

<ul>
  <li>User data can be automatically synced with Chrome sync
  (using <code>storage.sync</code>).</li>
  <li>Your {{platform}}'s content scripts can directly access user data
  without the need for a background page.</li>
  <li>A user's extension settings can be persisted
  even when using
  <a href="manifest/incognito.html">split incognito behavior</a>.</li>
  <li>It's asynchronous with bulk read and write operations, and therefore
  faster than the blocking and serial <code>localStorage API</code>.
  <li>User data can be stored as objects
  (the <code>localStorage API</code> stores data in strings).</li>
  <li>Enterprise policies configured by the administrator for the extension
  can be read (using <code>storage.managed</code> with a
  <a href="manifest/storage.html">schema</a>).</li>
</ul>

<h2 id="manifest">Manifest</h2>
<p>You must declare the "storage" permission in the <a
  href="manifest.html">extension manifest</a>
  to use the storage API.
  For example:</p>
<pre data-filename="manifest.json">
{
  "name": "My extension",
  ...
  <b>"permissions": [
    "storage"
  ]</b>,
  ...
}
</pre>

<h2 id="using-sync">Usage</h2>

<p>
To store user data for your {{platform}},
you can use either
<code>storage.sync</code> or
<code>storage.local</code>.
When using <code>storage.sync</code>,
the stored data will automatically be synced
to any Chrome browser that the user is logged into,
provided the user has sync enabled.
</p>

<p>
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,
<code>storage.sync</code> will still work.
In this case, it will behave identically
to <code>storage.local</code>.
</p>

<p class="warning">
Confidential user information should not be stored!
The storage area isn't encrypted.
</p>

<p>
The <code>storage.managed</code> storage is read-only.
</p>

<h2 id="limits">Storage and throttling limits</h2>

<p><code>chrome.storage</code> 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.

<p>For details on the current limits
of the storage API, and what happens
when those limits are exceeded, please
see the quota information for
<a href="#sync-properties">sync</a> and
<a href="#local-properties">local</a>.

<h2 id="examples">Examples</h2>

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

<pre>
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');
  });
}
</pre>

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

<pre>
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);
  }
});
</pre>