localStorage Guide: Safe Web Storage Patterns

Browser storage keeps small UI state across reloads: theme choice, language, cart drafts, and form drafts. The API is tiny, but the edge cases decide whether it works reliably.

This guide covers detection, safe serialization, cross-tab sync, and quota handling — the complete checklist for professional use.

How to detect localStorage support

Private browsing and disabled storage make setItem throw. Probe inside try/catch and fall back to memory so the app keeps running instead of crashing.

function storageAvailable() {
  try {
    const key = "__probe__";
    localStorage.setItem(key, "1");
    localStorage.removeItem(key);
    return true;
  } catch {
    return false;
  }
}

const memoryFallback = new Map();

const store = {
  get(key) {
    return storageAvailable()
      ? localStorage.getItem(key)
      : (memoryFallback.get(key) ?? null);
  },
  set(key, value) {
    if (storageAvailable()) localStorage.setItem(key, value);
    else memoryFallback.set(key, value);
  },
};

The rest of the app calls store.get and store.set without caring which backend is active.

How to store objects and dates correctly

Storage holds strings only. Plain objects need JSON.stringify and JSON.parse, while dates need a reviver function or they return as strings.

const ISO_DATE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;

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

function load(key, fallback = null) {
  const raw = localStorage.getItem(key);
  if (!raw) return fallback;
  try {
    return JSON.parse(raw, (k, v) =>
      typeof v === "string" && ISO_DATE.test(v) ? new Date(v) : v
    );
  } catch {
    return fallback;
  }
}

Why corrupted data must not crash the app

Users, extensions, and older app versions can leave invalid JSON behind. Parsing inside try/catch and returning a fallback keeps one bad key from breaking startup.

What to store — and what to avoid

Good candidates are small and non-sensitive: theme, locale, onboarding flags, cart drafts, and last-good API snapshots.

Never store access tokens, passwords, or personal data in localStorage. Any injected script can read it, so session secrets belong in httpOnly cookies.

How cross-tab sync works

The storage event fires in every other open tab when a value changes. This gives instant theme or cart updates without polling the server.

save("prefs", { theme: "dark" });

window.addEventListener("storage", (e) => {
  if (e.key === "prefs" && e.newValue) {
    const prefs = JSON.parse(e.newValue);
    document.documentElement.dataset.theme = prefs.theme;
  }
});

Remember that the tab performing the write does not receive the event. Update the active tab directly and let the event update the rest.

How to handle keys and storage quota

Browsers typically allow around 5MB. Namespaced keys such as prefs:, cache:, and draft: let cleanup remove only expendable data.

function listKeys(prefix = "") {
  const keys = [];
  for (let i = 0; i < localStorage.length; i++) {
    const key = localStorage.key(i);
    if (key && key.startsWith(prefix)) keys.push(key);
  }
  return keys;
}

function safeSet(key, value) {
  try {
    save(key, value);
  } catch (err) {
    if (err.name === "QuotaExceededError") {
      listKeys("cache:").forEach((k) => localStorage.removeItem(k));
      save(key, value);
    } else {
      throw err;
    }
  }
}

Real-world use cases

• Preferences: theme, locale, and sidebar state restored on load.
• Commerce: cart and checkout drafts preserved across reloads.
• Forms: long application drafts saved on change and cleared on submit.

Best practices for reliable storage

• Namespace every key so eviction never deletes unrelated data.
• Debounce writes from text inputs instead of saving every keystroke.
• Version stored shapes so older payloads can be migrated or ignored.
• Move large or relational data to IndexedDB or the server.

Common mistakes to avoid

• Storing auth tokens in localStorage instead of secure cookies.
• Assuming the storage event fires in the tab that wrote the value.
• Treating localStorage as a database for growing collections.

Frequently asked questions

How much can localStorage hold?

Usually around 5MB per origin. Exceeding it throws a QuotaExceededError, which is why quota-aware writes matter.

localStorage or sessionStorage?

Use localStorage for state that survives restarts, and sessionStorage for state scoped to one tab session such as a multi-step wizard.