Browser Extensions Development (Chrome & Edge) · Lesson

Using Chrome Storage API

Persist user settings and data securely and efficiently using the `chrome.storage` API for local and synced storage.

Using Chrome Storage API is a free Browser Extensions Development (Chrome & Edge) lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Browser Extensions Development (Chrome & Edge) learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Intro to Chrome Storage API

When building browser extensions, you often need to save data. This could be user settings, application state, or cached information.

The chrome.storage API provides a way to store data persistently, meaning it stays even after the browser closes or the extension is updated.

Why Use chrome.storage?

Unlike regular JavaScript variables, data stored with chrome.storage is persistent. Here's why it's a great choice for extensions:

Persistence: Data remains after the browser closes and across updates.
Security: It's isolated to your extension, preventing conflicts with other extensions or web pages.
Asynchronous: Operations don't block the main thread, keeping your extension responsive.
Key-Value Store: Easy to store and retrieve data as simple key-value pairs.

Local Storage: chrome.storage.local

The chrome.storage.local area is designed for storing data that should only be available on the current browser profile.

It's ideal for things like temporary user preferences, cached content, or data specific to one browser instance. The storage limit is typically 5MB.

Sync Storage: chrome.storage.sync

For data that users might want to access across different browsers or devices (if they are logged into their Google account), chrome.storage.sync is the solution.

It automatically syncs data across all instances where the user has your extension installed and is logged in. The storage limit is smaller, typically 100KB, with a maximum of 8KB per item.

storage vs. localStorage

You might be familiar with the browser's localStorage. While similar in purpose, chrome.storage is generally preferred for extensions due to key differences:

Asynchronous: chrome.storage is async, localStorage is sync (can block UI).
Security: chrome.storage is scoped to your extension.
Syncing: Only chrome.storage.sync offers cross-device syncing.
Availability: chrome.storage works in service workers, localStorage does not.

Saving Data with .set()

To save data, use the .set() method. It takes an object where keys are strings and values can be any JSON-serializable type.

This example saves a user's favorite color. This code would run in your extension's background script.

/* This code would typically run in your background.js */
/* (manifest.json would declare it as a service_worker) */

// Save a single item to local storage
chrome.storage.local.set({ 'favoriteColor': 'blue' }, function() {
  if (chrome.runtime.lastError) {
    console.error("Error saving color: ", chrome.runtime.lastError);
  } else {
    console.log("Favorite color saved!");
  }
});

// Save multiple items to sync storage
chrome.storage.sync.set({
  'userName': 'Coddy',
  'darkMode': true
}, function() {
  if (chrome.runtime.lastError) {
    console.error("Error saving user settings: ", chrome.runtime.lastError);
  } else {
    console.log("User settings saved to sync!");
  }
});

Retrieving Data with .get()

To get data back, use the .get() method. You can specify keys, or pass null to get all items.

The callback function receives an object containing the requested data, or an empty object if the key isn't found.

/* This code would typically run in your background.js */

// Get a single item from local storage
chrome.storage.local.get('favoriteColor', function(data) {
  const color = data.favoriteColor;
  if (color) {
    console.log("Your favorite color is: " + color);
  } else {
    console.log("Favorite color not set locally.");
  }
});

// Get multiple items from sync storage
chrome.storage.sync.get(['userName', 'darkMode'], function(data) {
  const userName = data.userName || 'Guest';
  const darkMode = data.darkMode || false;
  console.log(`Hello, ${userName}! Dark mode: ${darkMode}`);
});

// Get all items from local storage (use with caution for large data)
chrome.storage.local.get(null, function(data) {
  console.log("All local storage data:", data);
});

Removing Data: .remove() & .clear()

Sometimes you need to delete stored data. You can remove specific items or clear all data for your extension.

.remove(keys): Deletes one or more specific items.
.clear(): Removes all data from the storage area for your extension.

/* This code would typically run in your background.js */

// Remove a single item from local storage
chrome.storage.local.remove('favoriteColor', function() {
  if (chrome.runtime.lastError) {
    console.error("Error removing color: ", chrome.runtime.lastError);
  } else {
    console.log("Favorite color removed from local storage.");
  }
});

// Remove multiple items from sync storage
chrome.storage.sync.remove(['userName', 'darkMode'], function() {
  if (chrome.runtime.lastError) {
    console.error("Error removing settings: ", chrome.runtime.lastError);
  } else {
    console.log("User settings removed from sync storage.");
  }
});

// Clear all data from local storage (use with extreme caution!)
// chrome.storage.local.clear(function() {
//   if (chrome.runtime.lastError) {
//     console.error("Error clearing local storage: ", chrome.runtime.lastError);
//   } else {
//     console.log("Local storage cleared!");
//   }
// });

Listening for Storage Changes

Your extension can react when its stored data changes using the chrome.storage.onChanged event listener.

This is useful if different parts of your extension (like a popup and a background script) need to know when data is updated.

The listener provides details about what changed (newValue, oldValue) and in which storage area (local, sync).

/* This code would typically run in your background.js */

chrome.storage.onChanged.addListener(function(changes, areaName) {
  console.log("Storage area '" + areaName + "' changed.");
  for (let [key, { oldValue, newValue }] of Object.entries(changes)) {
    console.log(
      `Key "${key}" changed. ` +
      `Old value was "${oldValue}", new value is "${newValue}".`
    );
  }
});

// To demonstrate, let's change a value after a short delay
setTimeout(() => {
  chrome.storage.local.set({'favoriteColor': 'green'}, function() {
    if (!chrome.runtime.lastError) {
      console.log("Color updated to trigger onChanged listener.");
    }
  });
}, 2000);

Declaring the Storage Permission

To use the chrome.storage API, your extension needs to declare the "storage" permission in its manifest.json file.

Without this permission, attempts to use chrome.storage will fail with an error, and your extension won't be able to save or retrieve data.

{
  "manifest_version": 3,
  "name": "My Storage Extension",
  "version": "1.0",
  "permissions": [
    "storage"
  ],
  "background": {
    "service_worker": "background.js"
  }
}

Storage API Quick Check

Which of the following statements about chrome.storage are TRUE?

Recap: Mastering Data Persistence

You've learned how to persist data in your browser extensions using the chrome.storage API!

We covered .local for browser-specific data and .sync for cross-device syncing.
You now know how to .set(), .get(), .remove(), and .clear() data.
We also explored reacting to changes with .onChanged and the crucial "storage" permission.

This knowledge is vital for building robust and user-friendly extensions that remember user preferences and states.

Frequently asked questions

Is the “Using Chrome Storage API” lesson free?

Yes — the full text of “Using Chrome Storage API” is free to read here on the web, and the Browser Extensions Development (Chrome & Edge) course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Browser Extensions Development (Chrome & Edge) course, upgrade to CoddyKit PRO.

What will I learn in “Using Chrome Storage API”?

Persist user settings and data securely and efficiently using the `chrome.storage` API for local and synced storage. You practise Browser Extensions Development (Chrome & Edge) with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Browser Extensions Development (Chrome & Edge)?

No prior experience is required. Browser Extensions Development (Chrome & Edge) on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Using Chrome Storage API” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Browser Extensions Development (Chrome & Edge) lesson?

Yes. Every Browser Extensions Development (Chrome & Edge) lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Browser Extensions Development (Chrome & Edge)