Web Storage API

A developer built a dark mode toggle. Click the moon icon, the page goes dark. Refresh. Back to light mode. The toggle was updating a React state variable, but nobody persisted it. Two lines fixed it:

// On toggle
localStorage.setItem('theme', 'dark');
// On page load
const theme = localStorage.getItem('theme') || 'light';

The Web Storage API is the simplest persistence mechanism in the browser. No schema, no connections, no async callbacks. Just setItem, getItem, removeItem. But that simplicity hides sharp edges: synchronous blocking, string-only values, same-origin restrictions, and no built-in expiry. Understanding these constraints is the difference between a snappy app and one that freezes on mobile.

Both localStorage and sessionStorage share the exact same API. The only difference is lifetime and scope.

Core methods:

// Write
localStorage.setItem('user', JSON.stringify({ name: 'Roni', role: 'admin' }));

// Read
const user = JSON.parse(localStorage.getItem('user'));

// Delete one key
localStorage.removeItem('user');

// Delete everything
localStorage.clear();

// Iterate
for (let i = 0; i < localStorage.length; i++) {
  const key = localStorage.key(i);
  console.log(key, localStorage.getItem(key));
}

The string-only trap: Web Storage only stores strings. If you write localStorage.setItem('count', 42), reading it back gives you the string "42", not the number 42. Objects become "[object Object]" unless you JSON.stringify them. Every value must be serialized on write and deserialized on read.

Capacity varies by browser:

Safari's Intelligent Tracking Prevention can clear localStorage after 7 days of no user interaction on the domain. If your app relies on long-term localStorage persistence, Safari users may lose their data.