localStorage & sessionStorage

Two tiny browser shelves

Web Storage is a pair of simple browser APIs for saving small pieces of text on one origin: the exact combination of scheme, host, and port, such as https://example.com. The two shelves have the same methods but different lifetimes.

• localStorage keeps values after reloads, browser restarts, and return visits until your code or the user removes them.
• sessionStorage keeps values for one top-level tab. Reloading keeps them; closing the tab removes them. In most browsers, duplicating a tab starts with a copy.

Use Web Storage for preferences, UI state, feature tour flags, and small drafts that only the browser needs. Do not treat it like a database, a secure vault, or a server communication channel.

Both storage objects implement the same tiny interface. You write with setItem(key, value), read with getItem(key), remove one key with removeItem(key), inspect the number of stored keys with length, and ask for the key at an index with key(index). There is also clear(), but production code should use it carefully because it wipes every key for this origin, not only yours.

1const storage = localStorage;2 3storage.setItem("count", 7);4storage.setItem("darkMode", false);5storage.setItem("profile", { name: "Ada" });6 7console.log(storage.getItem("count"));8console.log(storage.getItem("darkMode"));9console.log(storage.getItem("profile"));10console.log(storage.getItem("missing"));

The important rule is that keys and values are strings. The browser applies String(value) before saving. A number comes back as "7", a boolean as "false", and a plain object as "[object Object]". Missing keys return null, which is why you will often see localStorage.getItem("tab") ?? "overview".

The fix for plain objects is the JSON lesson’s pattern: turn data into text with JSON.stringify, then turn the text back into data with JSON.parse. Because stored text can be missing, old, manually edited in DevTools, or left behind by an older version of your app, read it defensively with try/catch.

1function readJSON(key, fallback) {2  const text = localStorage.getItem(key);3  if (text === null) return fallback;4  try {5    return JSON.parse(text);6  } catch {7    return fallback;8  }9}10 11const oldSettings = {12  version: 1,13  data: { theme: "dark", compact: true }14};15localStorage.setItem("cf-demo:settings", JSON.stringify(oldSettings));16 17const loaded = readJSON("cf-demo:settings", { version: 2, data: {} });18const current = loaded.version === 119  ? { version: 2, data: { ...loaded.data, textSize: "normal" } }20  : loaded;21 22localStorage.setItem("cf-demo:settings", JSON.stringify(current));

Versioning matters as soon as real users have saved data. Store an envelope like { version: 2, data: settings }. When you load an older version, migrate it to the newest shape before the rest of your app uses it. That keeps the messy compatibility code in one place.

When one document changes localStorage or sessionStorage, other same-origin documents can receive a storage event. The document that made the change does not receive its own event. That keeps it useful for cross-tab coordination, not as a replacement for your current component’s state update.

1window.addEventListener("storage", (event) => {2  console.log(event.key);3  console.log(event.oldValue);4  console.log(event.newValue);5  console.log(event.url);6  console.log(event.storageArea === localStorage);7});8 9localStorage.setItem("cf-demo:signal", "hello");

If clear() is used, event.key is null. In this lesson’s demos we avoid localStorage.clear() and remove only keys that start with cf-demo:, because this website may have its own unrelated keys such as theme preferences.

A common use is remembering the last tab, panel, or filter a visitor chose. The pattern is deliberately small: read with a fallback, let the user choose, write the new string, then read it on the next visit. The execution below is recorded from a testable in-memory Storage model, because Node does not provide browser localStorage by default.

1const storage = makeStorage();Run2const fallback = "overview";3let activeTab = storage.getItem("lastTab") ?? fallback;4 5activeTab = "examples";6storage.setItem("lastTab", activeTab);7 8const nextVisit = storage.getItem("lastTab") ?? fallback;9console.log(nextVisit);

Notice that storage is not the live source of truth for every click. Your UI state changes immediately, then you persist the latest choice. On page load, storage simply helps choose the initial state.

Web Storage is convenient, but it is intentionally small and simple. Browsers commonly allow around a few megabytes per origin, often around 5 MB, but the real limit varies. setItem can throw a QuotaExceededError DOMException when the browser refuses a write, so production code should catch it and degrade gracefully.

1try {2  localStorage.setItem("cf-demo:settings", jsonText);3} catch (error) {4  // QuotaExceededError or storage unavailable: fall back gracefully.5}

The next lesson is IndexedDB, a real browser database. For now, keep the decision tree simple: Web Storage is for small client-only strings, cookies are for tiny values the server needs, and IndexedDB is for larger structured client data.

Common misconceptions

• “It stores JavaScript values.” It stores strings. Use JSON for plain data and rebuild special types like Date deliberately.
• “sessionStorage disappears on refresh.” It survives reloads. It disappears when that top-level tab session ends.
• “Every tab shares sessionStorage.” Tabs on the same origin share localStorage, but each top-level tab gets its own sessionStorage area.
• “The storage event tells my current page it wrote.” It fires in other same-origin documents, not the writer.
• “It is safe because users cannot see it.” Users and scripts can inspect it. Never put secrets there.
• “clear() is a harmless reset.” It wipes the whole storage area for the origin. Prefer removing your own namespaced keys.

Key takeaways

• localStorage is per-origin and long-lived; sessionStorage is per-origin and per-tab.
• Keys and values are strings. Missing getItem results are null.
• Use JSON, fallbacks, try/catch, and version migrations for real data.
• The storage event fires in other same-origin documents, not the writer.
• Catch quota failures, avoid secrets, and choose IndexedDB or cookies when they fit better.

Final definition: Web Storage is a synchronous, string-only, per-origin browser key/value API for small client-side data that should live either across visits or within one tab session.

Up next: IndexedDB.