chrome.storage

Use the chrome.storage API to store, retrieve, and track changes to user data.

Overview #

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:

• User data can be automatically synced with Chrome sync (using storage.sync ).
• Your extension’s content scripts can directly access user data without the need for a background page.
• A user’s extension settings can be persisted even when using split incognito behavior.
• 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:

Usage #

To store user data for your extension, you can use either storage.sync :

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 #

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.extension

The chrome.extension API has utilities that can be used by any extension page. It includes support for exchanging messages between an extension and its content scripts or between extensions, as described in detail in Message Passing.

Summary

Types

ViewType

Since Chrome 44.

The type of extension view.

Properties

inIncognitoContext

True for content scripts running inside incognito tabs, and for extension pages running inside an incognito process. The latter only applies to extensions with ‘split’ incognito_behavior.

lastError

Deprecated since Chrome 58. Please use runtime.lastError .

Set for the lifetime of a callback if an ansychronous extension api has resulted in an error. If no error has occured lastError will be undefined .

Properties

Description of the error that has taken place.

Methods

getBackgroundPage

Returns the JavaScript ‘window’ object for the background page running inside the current extension. Returns null if the extension has no background page.

Returns

getExtensionTabs

Deprecated. Please use getViews .

Returns an array of the JavaScript ‘window’ objects for each of the tabs running inside the current extension. If windowId is specified, returns only the ‘window’ objects of tabs attached to the specified window.

Parameters

Returns

Array of global window objects

getURL

Deprecated since Chrome 58. Please use runtime.getURL .

Converts a relative path within an extension install directory to a fully-qualified URL.

Parameters

A path to a resource within an extension expressed relative to its install directory.

Getting started

Published on Friday, February 28, 2014 • Updated on Wednesday, November 18, 2020

The page you’re viewing describes extensions using Manifest V2. Now that Manifest V3 has launched, we strongly recommend that you use it for any new extensions that you create.

Extensions are made of different, but cohesive, components. Components can include background scripts, content scripts, an options page, UI elements and various logic files. Extension components are created with web development technologies: HTML, CSS, and JavaScript. An extension’s components will depend on its functionality and may not require every option.

This tutorial will build an extension that allows the user to change the background color of any page on developer.chrome.com. It will use many core components to give an introductory demonstration of their relationships.

To start, create a new directory to hold the extension’s files.

The completed extension can be downloaded here.

Create the manifest #

Extensions start with their manifest. Create a file called manifest.json and include the following code, or download the file here.

The directory holding the manifest file can be added as an extension in developer mode in its current state.

1. Open the Extension Management page by navigating to chrome://extensions .
   • The Extension Management page can also be opened by clicking on the Chrome menu, hovering over More Tools then selecting Extensions.
2. Enable Developer Mode by clicking the toggle switch next to Developer mode.
3. Click the LOAD UNPACKED button and select the extension directory.

Ta-da! The extension has been successfully installed. Because no icons were included in the manifest, a generic toolbar icon will be created for the extension.

Add instruction #

Although the extension has been installed, it has no instruction. Introduce a background script by creating a file titled background.js , or downloading it here, and placing it inside the extension directory.

Background scripts, and many other important components, must be registered in the manifest. Registering a background script in the manifest tells the extension which file to reference, and how that file should behave.

The extension is now aware that it includes a non-persistent background script and will scan the registered file for important events it needs to listen for.

This extension will need information from a persistent variable as soon as it’s installed. Start by including a listening event for runtime.onInstalled in the background script. Inside the onInstalled listener, the extension will set a value using the storage API. This will allow multiple extension components to access that value and update it.

Most APIs, including the storage API, must be registered under the «permissions» field in the manifest for the extension to use them.

Navigate back to the extension management page and click the Reload link. A new field, Inspect views, becomes available with a blue link, background page.

Click the link to view the background script’s console log, » The color is green. «

Introduce a user interface #

Extensions can have many forms of a user interface, but this one will use a popup. Create and add a file titled popup.html to the directory, or download it here. This extension uses a button to change the background color.

Like the background script, this file needs to be designated as a popup in the manifest under page_action .

Designation for toolbar icons is also included under page_action in the default_icons field. Download the images folder here, unzip it, and place it in the extension’s directory. Update the manifest so the extension knows how to use the images.

Extensions also display images on the extension management page, the permissions warning, and favicon. These images are designated in the manifest under icons .

If the extension is reloaded at this stage, it will include a grey-scale icon, but will not contain any functionality differences. Because page_action is declared in the manifest, it is up to the extension to tell the browser when the user can interact with popup.html .

Add declared rules to the background script with the declarativeContent API within the runtime.onInstalled listener event.

The extension will need permission to access the declarativeContent API in its manifest.

The browser will now show a full-color page action icon in the browser toolbar when users navigate to a URL that contains «developer.chrome.com» . When the icon is full-color, users can click it to view popup.html.

The last step for the popup UI is adding color to the button. Create and add a file called popup.js with the following code to the extension directory, or downloaded here.

This code grabs the button from popup.html and requests the color value from storage. It then applies the color as the background of the button. Include a script tag to popup.js in popup.html .

Reload the extension to view the green button.

Layer logic #

The extension now knows the popup should be available to users on developer.chrome.com and displays a colored button, but needs logic for further user interaction. Update popup.js to include the following code.

The updated code adds an onclick event on the button, which triggers a programatically injected content script. This turns the background color of the page the same color as the button. Using programmatic injection allows for user-invoked content scripts, instead of auto inserting unwanted code into web pages.

The manifest will need the activeTab permission to allow the extension temporary access to the tabs API. This enables the extension to call tabs.executeScript .

The extension is now fully functional! Reload the extension, refresh this page, open the popup and click the button to turn it green! However, some users may want to change the background to a different color.

Give users options #

The extension currently only allows users to change the background to green. Including an options page gives users more control over the extension’s functionality, further customizing their browsing experience.

Start by creating a file in the directory called options.html and include the following code, or download it here.

Then register the options page in the manifest,

Reload the extension and click DETAILS.

Scroll down the details page and select Extension options to view the options page, although it will currently appear blank.

Last step is to add the options logic. Create a file called options.js in the extension directory with the following code, or download it here.

Four color options are provided then generated as buttons on the options page with onclick event listeners. When the user clicks a button, it updates the color value in the extension’s global storage. Since all of the extension’s files pull the color information from global storage no other values need to be updated.

Take the next step #

Congratulations! The directory now holds a fully-functional, albeit simplistic, Chrome extension.

• The Chrome Extension Overview backs up a bit, and fills in a lot of detail about the Extensions architecture in general, and some specific concepts developers will want to be familiar with.
• Learn about the options available for debugging Extensions in the debugging tutorial.
• Chrome Extensions have access to powerful APIs above and beyond what’s available on the open web. The chrome.* APIs documentation will walk through each API.
• The developer’s guide has dozens of additional links to pieces of documentation relevant to advanced extension creation.

Last updated: Wednesday, November 18, 2020 Improve article

Extension development overview

Published on Monday, September 17, 2012 • Updated on Tuesday, June 12, 2018

The page you’re viewing describes extensions using Manifest V2. Now that Manifest V3 has launched, we strongly recommend that you use it for any new extensions that you create.

After reading the Getting Started tutorial and Overview, use this guide as an outline to extension components and abilities. Developers are encouraged to explore and expand extension functionality.

Customize extension user interface
Browser Actions	Add an icon, tooltip, badge, and popup to the toolbar.
Commands	Add keyboard shortcuts that trigger actions.
Context Menus	Add items to Google Chrome’s context menu.
Omnibox	Add keyword functionality to the address bar.
Override Pages	Create a version of the New Tab, Bookmark, or History page.
Page Actions	Dynamically display icons in the toolbar.

Build extension utilities
Accessibility (a11y)	Make an extension accessible to people with disabilities.
Background Scripts	Detect and react when something interesting happens.
Internationalization	Work with language and locale.
Identity	Get OAuth2 access tokens.
Management	Manage extensions that are installed and running.
Message Passing	Communicate from a content script to its parent extension, or vice versa.
Options Pages	Let users customize an extension.
Permissions	Modify an extension’s permissions.
Storage	Store and retrieve data.

Modify and observe the Chrome Browser
Bookmarks	Create, organize, and manipulate bookmark behavior.
Browsing Data	Remove browsing data from a user’s local profile.
Downloads	Programmatically initiate, monitor, manipulate, and search for downloads.
Font Settings	Manage Chrome’s font settings.
History	Interact with the browser’s record of visited pages.
Privacy	Control Chrome privacy features.
Proxy	Manage Chrome’s proxy settings.
Sessions	Query and restore tabs and windows from a browsing session.
Tabs	Create, modify, and rearrange tabs in the browser.
Top Sites	Access users most visited URLs.
Themes	Change the overall appearance of the browser.
Windows	Create, modify, and rearrange windows in the browser.

Modify and observe the web
Active Tab	Securely access websites by removing most needs for host permission.
Content Settings	Customize websites features such as cookies, JavaScript, and plugins.
Content Scripts	Run JavaScript code in the context of web pages.
Cookies	Explore and modify the browser’s cookie system.
Cross-Origin XHR	Use XMLHttpRequest to send and receive data from remote servers.
Declarative Content	Perform actions on the content of a page without requiring permission.
Desktop Capture	Capture content of screen, individual windows or tabs.
Page Capture	Save a tab’s source information as MHTML.
Tab Capture	Interact with tab media streams.
Web Navigation	Status updates of navigation requests in-flight.
Web Request	Observe and analyze traffic. Intercept block, or modify requests in-flight.

Package, deploy and update
Chrome Web Store	Hosting and updating extensions with the Chrome Web Store.
Other Deployment Options	Distribute extensions on a designated network or with other software.

Expand Chrome DevTools
Debugger	Instrument network interaction, debug JavaScript, mutate the DOM and CSS.
Devtools	Add features to Chrome Developer Tools.

Last updated: Tuesday, June 12, 2018 Improve article