💾 Local Storage and Session Storage

What Is Web Storage?

The Web Storage API lets a website keep small amounts of data directly inside the user's browser, tied to your site's origin. Before it existed, developers stuffed everything into cookies — which are limited to about 4 KB, are sent to the server on every single request (wasting bandwidth), and require awkward string parsing.

Web Storage fixes all three problems: roughly 5 MB of room per origin, data that stays in the browser and is never automatically transmitted, and a dead-simple key/value interface.

💡 A useful analogy: localStorage is a filing cabinet in your office — it's still there tomorrow when you come back. sessionStorage is a whiteboard in a meeting room — perfect for working notes, but wiped clean the moment you leave.

localStorage vs sessionStorage

Both objects expose the exact same API. The only difference is lifetime and scope:

How a "session" behaves

• Navigating within the same tab keeps sessionStorage.
• Reloading or restoring the page keeps it.
• Opening the same site in a new tab starts a fresh, empty sessionStorage.
• Duplicating a tab copies the current sessionStorage into the new one.
• Closing the tab destroys it.

The Core API

Five methods and one property cover everything. Every value is stored and returned as a string — remember that, because it trips up almost everyone at least once.

// Store values (both arguments are coerced to strings)
localStorage.setItem('username', 'ada_lovelace');
localStorage.setItem('visits', '1');

// Read a value back — returns null if the key is missing
const name = localStorage.getItem('username'); // 'ada_lovelace'
const missing = localStorage.getItem('nope');  // null

// Remove one key, or wipe everything for this origin
localStorage.removeItem('visits');
// localStorage.clear();

// Inspect the store
console.log(localStorage.length);   // number of keys
console.log(localStorage.key(0));   // the key at index 0

You can also use property syntax (localStorage.username = 'ada'), but prefer the methods — they read more clearly and avoid clashing with built-in property names like length or clear.

Storing Objects & Arrays

Because storage only holds strings, structured data must be run through JSON on the way in and out.

const prefs = {
  theme: 'dark',
  fontSize: 16,
  notifications: { email: true, push: false }
};

// Serialize to a string before storing
localStorage.setItem('prefs', JSON.stringify(prefs));

// Parse back into an object when reading
const saved = JSON.parse(localStorage.getItem('prefs'));
console.log(saved.notifications.email); // true

A robust read guards against a missing or corrupted value so one bad entry can't crash your app:

function readJSON(key, fallback = null) {
  const raw = localStorage.getItem(key);
  if (raw === null) return fallback;
  try {
    return JSON.parse(raw);
  } catch {
    console.warn(`Corrupt JSON in "${key}" — using fallback`);
    return fallback;
  }
}

const searches = readJSON('recentSearches', []); // always an array

Cross-Tab Sync & Expiry

The storage event

When localStorage changes in one tab, every other tab on the same origin fires a storage event. (The tab that made the change does not receive it.) This gives you free cross-tab synchronization — change a setting in one tab and watch the others update live.

window.addEventListener('storage', (event) => {
  if (event.key === 'prefs') {
    console.log('Prefs changed in another tab');
    console.log('old:', event.oldValue, 'new:', event.newValue);
    applyPreferences(JSON.parse(event.newValue));
  }
});

Adding your own expiry

Unlike cookies, Web Storage has no built-in expiration. You can bolt it on by storing a timestamp alongside the value:

function setWithExpiry(key, value, ttlMs) {
  const record = { value, expiresAt: Date.now() + ttlMs };
  localStorage.setItem(key, JSON.stringify(record));
}

function getWithExpiry(key) {
  const raw = localStorage.getItem(key);
  if (!raw) return null;
  const { value, expiresAt } = JSON.parse(raw);
  if (Date.now() > expiresAt) {
    localStorage.removeItem(key); // lazily evict on read
    return null;
  }
  return value;
}

// Cache a result for 10 minutes
setWithExpiry('rates', { usd: 1.0 }, 10 * 60 * 1000);

Limits & Security

Quota handling

When you exceed the ~5 MB limit, setItem throws a QuotaExceededError. Never let that crash a save — wrap it:

function safeSet(key, value) {
  try {
    localStorage.setItem(key, value);
    return true;
  } catch (err) {
    if (err.name === 'QuotaExceededError') {
      console.warn('Storage full — evicting old data');
      evictOldEntries();
      return false;
    }
    throw err; // some other, unexpected error
  }
}

Also note: some browsers block or wipe storage in private/incognito mode, and Safari may throw the moment you call setItem. Feature-detect before relying on it:

function storageAvailable() {
  try {
    const t = '__test__';
    localStorage.setItem(t, t);
    localStorage.removeItem(t);
    return true;
  } catch {
    return false; // disabled, full, or private mode
  }
}

Hands-on: Auto-Saving Form

<form id="application">
  <input name="fullName" placeholder="Full name">
  <input name="email" type="email" placeholder="Email">
  <textarea name="coverLetter" placeholder="Cover letter"></textarea>
  <button type="submit">Submit</button>
</form>
<p id="status" aria-live="polite"></p>

const form = document.getElementById('application');
const status = document.getElementById('status');
const KEY = 'applicationDraft';

// 1. Restore on load
const draft = JSON.parse(localStorage.getItem(KEY) || '{}');
for (const [name, value] of Object.entries(draft)) {
  if (form.elements[name]) form.elements[name].value = value;
}

// 2. Save on input (debounced)
let timer;
form.addEventListener('input', () => {
  clearTimeout(timer);
  timer = setTimeout(() => {
    const data = Object.fromEntries(new FormData(form));
    localStorage.setItem(KEY, JSON.stringify(data));
    status.textContent = 'Draft saved ' + new Date().toLocaleTimeString();
  }, 400);
});

// 3. Clear on submit
form.addEventListener('submit', (e) => {
  e.preventDefault();
  localStorage.removeItem(KEY);
  status.textContent = 'Submitted — draft cleared';
  form.reset();
});

Best Practices

Summary & Quiz

📚 Further Reading

• MDN — Web Storage API
• MDN — localStorage
• web.dev — Storage for the Web

🚀 What's Next?

Next we leave the filing cabinet behind and ask the browser a very different question: where are you? The Geolocation API lets your app read the user's coordinates — with their permission — to power maps, store finders, and weather.