JS Web Storage

Web Storage lets a page keep small pieces of data in the visitor's own browser: a chosen theme, a half-written note, a game score. It works like a tiny object that survives page reloads, and it is far simpler than cookies. This lesson covers the two kinds of storage, the handful of methods, the strings-only rule that sends everything through JSON, and the limits to know about.

A note about the examples. Your code in the Try It editor runs on this site, so the storage it uses is the same storage this site uses for your themes, notes, and saved drafts. Every example here uses keys that start with demo_ and cleans up after itself. Never call localStorage.clear() here: it would erase your saved notes and settings for this whole site.

// Two Kinds of Storage

Both have exactly the same methods, so everything below works for either. Storage belongs to one origin (the protocol, host, and port): a page on one site can never read what another site stored.

// The Five Things You Can Do

localStorage.setItem("demo_name", "Ava");
console.log(localStorage.getItem("demo_name"));
console.log(localStorage.getItem("demo_missing"));

localStorage.removeItem("demo_name");
console.log(localStorage.getItem("demo_name"));

There is also a shorthand that treats storage like an object (localStorage.demo_name = "Ava"), but setItem and getItem are clearer and safer, so use them.

// Everything Is a String

Storage keeps only strings. Anything else is turned into text on the way in, and comes back as text:

localStorage.setItem("demo_count", 5);
const value = localStorage.getItem("demo_count");

console.log(typeof value);
console.log(value + 1);
console.log(Number(value) + 1);

localStorage.removeItem("demo_count");

// Saving Objects: JSON to the Rescue

const settings = { theme: "dark", fontSize: 18, tags: ["a", "b"] };

localStorage.setItem("demo_settings", JSON.stringify(settings));

const loaded = JSON.parse(localStorage.getItem("demo_settings"));
console.log(loaded.theme, loaded.fontSize + 2, loaded.tags.length);

localStorage.removeItem("demo_settings");

// Two Small Helpers

Because getItem returns null for a missing key, and JSON.parse throws on bad text, it is worth wrapping the pattern once:

function save(key, value) {
  localStorage.setItem(key, JSON.stringify(value));
}

function load(key, fallback) {
  const text = localStorage.getItem(key);
  if (text === null) return fallback;
  try {
    return JSON.parse(text);
  } catch (error) {
    return fallback;
  }
}

console.log(load("demo_score", 0));
save("demo_score", 42);
console.log(load("demo_score", 0));

localStorage.setItem("demo_bad", "{oops");
console.log(load("demo_bad", "recovered"));

localStorage.removeItem("demo_score");
localStorage.removeItem("demo_bad");

// Listing What Is Stored

localStorage.length and localStorage.key(i) let you loop through every key. Because this site stores its own keys too, the example filters to the demo_ ones:

localStorage.setItem("demo_b", "2");
localStorage.setItem("demo_a", "1");

const mine = [];
for (let i = 0; i < localStorage.length; i++) {
  const key = localStorage.key(i);
  if (key.startsWith("demo_")) mine.push(key);
}
console.log(mine.sort());

localStorage.removeItem("demo_a");
localStorage.removeItem("demo_b");

// A Page That Remembers

Here a button counts clicks and the count survives a reload. Close the Result pane and run it again: the number is still there. The Reset button clears it:

<p>Clicks: <strong id="n">0</strong></p>
<button id="add">Click me</button>
<button id="reset">Reset</button>

<script>
  const n = document.getElementById("n");
  let count = Number(localStorage.getItem("demo_clicks")) || 0;
  n.textContent = count;

  document.getElementById("add").addEventListener("click", function () {
    count++;
    n.textContent = count;
    localStorage.setItem("demo_clicks", count);
  });

  document.getElementById("reset").addEventListener("click", function () {
    count = 0;
    n.textContent = 0;
    localStorage.removeItem("demo_clicks");
  });
</script>

// sessionStorage

sessionStorage is used the same way. The only difference is that the data disappears when the tab closes, which suits things like the step of a form the person is partway through:

sessionStorage.setItem("demo_step", "2");
console.log(sessionStorage.getItem("demo_step"));
console.log(localStorage.getItem("demo_step"));
sessionStorage.removeItem("demo_step");

// Limits and Cautions

• About 5 MB per site. Going over throws a QuotaExceededError, so wrap big saves in try...catch
• It is synchronous: a huge read or write freezes the page while it happens
• Anyone using that browser can read and change it (open the developer tools, Application tab). Never store passwords, tokens, or private data
• It is not shared between browsers or devices, and it is wiped if the person clears site data. Treat it as a convenience, not a database
• In some private-browsing modes it is unavailable or throws, so code defensively
• Unlike cookies, it is never sent to the server automatically

// Storage Across Tabs: the storage Event

When one tab changes localStorage, every other tab of the same site gets a "storage" event, which lets tabs stay in sync (a theme change, a logout). The tab that made the change does not get it:

window.addEventListener("storage", function (event) {
  console.log(event.key, "changed from", event.oldValue, "to", event.newValue);
});

// Quick Check

localStorage.setItem("demo_n", 5);
console.log(typeof localStorage.getItem("demo_n"));
localStorage.removeItem("demo_n");

const user = { name: "Ava" };
localStorage.setItem("demo_u", user);
console.log(localStorage.getItem("demo_u"));
localStorage.removeItem("demo_u");

// Try It

▶ Open Playground

1. Click Open Playground and run it. Run it again: what changed?
2. Save an array of three names with the helpers and load it back
3. Make a note-taking box that saves its text as you type and shows it again after a reload
4. Change the counter to use sessionStorage and explain the difference you see