Browser Storage

Persisting data in the browser — localStorage, sessionStorage, IndexedDB, cookies, and Cache API.

What it is, in plain English: Browser storage lets JavaScript save data that survives page refreshes and tab closures. localStorage stores key-value string pairs indefinitely (until cleared). sessionStorage stores them only for the current tab session. IndexedDB is a full database for large structured data. Cookies are sent to the server with every request and can be set from either client or server. Cache API stores network responses for offline use.

Where this bites you

JSON.stringify turns a Date into a string, and JSON.parse leaves it as a string. So a date saved to localStorage, even through a careful wrapper, comes back as text like "2026-10-18T…Z". The first call to .getTime() or .getFullYear() on it throws, and that's often in code far from where the date was saved.

localStorage.setItem("lastVisit", JSON.stringify(new Date()));

const lastVisit = JSON.parse(localStorage.getItem("lastVisit"));
console.log(typeof lastVisit);
console.log(lastVisit.getTime());
// string
// TypeError: lastVisit.getTime is not a function

Saving data in the browser

By default, JavaScript variables disappear when the page refreshes. Browser storage APIs let you save data that persists — across refreshes, across sessions, and even offline.

localStorage — the most common choice

// Store a string:
localStorage.setItem("city", "Mumbai");

// Retrieve it:
console.log(localStorage.getItem("city"));  // "Mumbai"

// Missing key returns null (not undefined):
console.log(localStorage.getItem("missing"));  // null

// Remove one item:
localStorage.removeItem("city");

// Clear everything:
localStorage.clear();

// ─ KEY LIMITATION: everything is a string ─
// Objects must be JSON-encoded:
const user = { name: "Alice", score: 95 };
localStorage.setItem("user", JSON.stringify(user));   // store

const loaded = JSON.parse(localStorage.getItem("user"));  // retrieve
console.log(loaded.name);   // "Alice"

localStorage stores strings only. Numbers, booleans, and objects must be converted with JSON.stringify when storing and JSON.parse when reading. Forgetting this is the most common localStorage mistake.

sessionStorage — same API, tab-only

// Same API as localStorage, but data is cleared when the tab closes:
sessionStorage.setItem("step", "2");  // wizard step
console.log(sessionStorage.getItem("step"));  // "2"

// Use sessionStorage for:
// - Multi-step form data (gone if they close the tab — intentional)
// - Temporary UI state that shouldn't persist
// - Per-tab settings

A safe storage wrapper

// Wrap localStorage to handle JSON automatically and errors gracefully:
const store = {
  get(key, fallback = null) {
    try {
      const item = localStorage.getItem(key);
      return item !== null ? JSON.parse(item) : fallback;
    } catch {
      return fallback;
    }
  },

  set(key, value) {
    try {
      localStorage.setItem(key, JSON.stringify(value));
      return true;
    } catch (e) {
      // QuotaExceededError — storage is full
      console.warn("Storage full:", e.message);
      return false;
    }
  },

  remove(key) { localStorage.removeItem(key); },
  clear()     { localStorage.clear(); },
};

// Usage:
store.set("settings", { theme: "dark", fontSize: 16 });
const { theme } = store.get("settings", { theme: "light" });
console.log(theme);  // "dark"

The store wrapper above has the same limit: it handles JSON-friendly values (strings, numbers, booleans, plain objects and arrays), and everything else comes back changed. For dates, save a timestamp, which is a plain number, and rebuild the Date when you read it:

localStorage.setItem("lastVisit", JSON.stringify(Date.now()));   // a timestamp is a plain number

const lastVisit = new Date(JSON.parse(localStorage.getItem("lastVisit")));   // turn it back into a Date
console.log(lastVisit instanceof Date);
console.log(lastVisit.getFullYear());
// true
// 2026

Cookies vs localStorage

localStorage

Sent to server

Never

Every request

Expiry

Until cleared

Configurable

Size

~5MB

~4KB per cookie

Access

JS only

JS + server (unless HttpOnly)

Best for

Client-side preferences, cache

Sessions, auth tokens

Try It Yourself

// localStorage — persists until explicitly cleared
// Keys and values are always strings

// Store data (must stringify objects):
localStorage.setItem("username", "Alice");
localStorage.setItem("settings", JSON.stringify({ theme: "dark", lang: "en" }));

// Retrieve:
const name     = localStorage.getItem("username");
const settings = JSON.parse(localStorage.getItem("settings") ?? "{}");
console.log(name);             // "Alice"
console.log(settings.theme);  // "dark"

// Check if key exists:
console.log(localStorage.getItem("missing"));  // null (not undefined)

// Remove one key:
localStorage.removeItem("username");

// Clear everything (careful!):
// localStorage.clear();

// Iterate all keys:
for (let i = 0; i < localStorage.length; i++) {
  const key   = localStorage.key(i);
  const value = localStorage.getItem(key);
  console.log(`${key}: ${value}`);
}

// sessionStorage — same API, but only lasts for the tab session
sessionStorage.setItem("tempData", "only for this tab");
console.log(sessionStorage.getItem("tempData"));  // "only for this tab"
// Cleared when the tab/browser is closed

// Safe wrapper (handles JSON + missing keys):
const storage = {
  get(key, fallback = null) {
    try { return JSON.parse(localStorage.getItem(key)) ?? fallback; }
    catch { return fallback; }
  },
  set(key, value) {
    try { localStorage.setItem(key, JSON.stringify(value)); return true; }
    catch { return false; }  // QuotaExceededError
  },
  remove(key) { localStorage.removeItem(key); },
};

storage.set("user", { name: "Bob", score: 95 });
console.log(storage.get("user").name);   // "Bob"
console.log(storage.get("missing", 42)); // 42 (fallback)

IndexedDB, storage events, and quota

IndexedDB — for large structured data

// IndexedDB is async, supports transactions, indexes, and large data.
// The raw API is verbose — use the 'idb' wrapper library in real projects.

// With idb (npm install idb):
import { openDB } from "idb";

const db = await openDB("my-database", 1, {
  upgrade(db) {
    // Called when DB doesn't exist or version increases
    const store = db.createObjectStore("users", { keyPath: "id" });
    store.createIndex("byName", "name");  // enable search by name
  },
});

// Add data:
await db.put("users", { id: 1, name: "Alice", score: 95 });
await db.put("users", { id: 2, name: "Bob",   score: 87 });

// Read by key:
const alice = await db.get("users", 1);
console.log(alice.name);  // "Alice"

// Read all:
const all = await db.getAll("users");
console.log(all.length);  // 2

// Search by index:
const byName = await db.getFromIndex("users", "byName", "Bob");
console.log(byName.score);  // 87

// Delete:
await db.delete("users", 1);

storage event — sync across tabs

// localStorage changes in one tab fire a "storage" event in OTHER tabs:
window.addEventListener("storage", (event) => {
  console.log("Key changed:", event.key);
  console.log("Old value:", event.oldValue);
  console.log("New value:", event.newValue);
  console.log("From URL:", event.url);

  if (event.key === "theme") {
    applyTheme(event.newValue);  // sync theme across all tabs
  }
});

// Note: the event does NOT fire in the same tab that made the change!

Storage quota

// Check how much storage you have available:
if ("storage" in navigator && "estimate" in navigator.storage) {
  const { usage, quota } = await navigator.storage.estimate();
  console.log(`Used: ${(usage / 1024 / 1024).toFixed(2)} MB`);
  console.log(`Available: ${(quota / 1024 / 1024).toFixed(2)} MB`);
}

// Typical quotas:
// localStorage:  5MB (strings only)
// IndexedDB:     up to 60% of free disk space
// Cache API:     up to 60% of free disk space

// Request persistent storage (won't be evicted under pressure):
const granted = await navigator.storage.persist();
console.log("Persistent storage granted:", granted);

Cache API and Storage spec

Cache API — store network responses

// Cache API stores Request/Response pairs (used in Service Workers):
const cache = await caches.open("v1");

// Add a URL to the cache:
await cache.add("/api/config");  // fetches and stores

// Or store a custom response:
await cache.put(
  new Request("/api/user/1"),
  new Response(JSON.stringify({ id: 1, name: "Alice" }), {
    headers: { "Content-Type": "application/json" }
  })
);

// Retrieve:
const res = await cache.match("/api/config");
if (res) console.log(await res.json());

// List all cached URLs:
const requests = await cache.keys();
requests.forEach(r => console.log(r.url));

// Delete a cache version during SW update:
await caches.delete("v1");

Web Storage spec (HTML Living Standard)

Web Storage (localStorage, sessionStorage) is defined in the HTML Living Standard §12. Each storage area is a Storage object backed by a per-origin key-value store. Origin isolation is enforced: http://example.com and https://example.com are different origins with separate storage. The spec defines a 5MB-per-origin soft limit, though implementations vary. The storage event is dispatched on all WindowProxy objects with the same origin as the affected storage object, except the one that made the change.

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.