Local Storage

localStorage provides key-value storage that persists across browser sessions.

Basic Operations

// Set item
localStorage.setItem('theme', 'dark');
localStorage.setItem('user', JSON.stringify({ name: 'Alice', age: 25 }));

// Get item
const theme = localStorage.getItem('theme');  // 'dark'
const user = JSON.parse(localStorage.getItem('user'));  // {name: 'Alice', age: 25}

// Remove item
localStorage.removeItem('theme');

// Clear all
localStorage.clear();

// Get length
const count = localStorage.length;

// Get key by index
const key = localStorage.key(0);

Bracket Notation

// Alternative syntax (like an object)
localStorage['theme'] = 'dark';
const theme = localStorage['theme'];

delete localStorage['theme'];

Storage Event

// Listen for changes (from other tabs/windows)
window.addEventListener('storage', (event) => {
  console.log('Key:', event.key);
  console.log('Old value:', event.oldValue);
  console.log('New value:', event.newValue);
  console.log('URL:', event.url);
});

Common Use Cases

// Theme preference
localStorage.setItem('theme', 'dark');

// Form draft
localStorage.setItem('draft-form', JSON.stringify(formData));

// User preferences
localStorage.setItem('preferences', JSON.stringify({
  language: 'en',
  notifications: true,
  fontSize: 14
}));

// Cache API responses
localStorage.setItem('cache-users', JSON.stringify({
  data: users,
  timestamp: Date.now()
}));

localStorage is useful for persisting non-sensitive data on the client.

Good Use Cases

Bad Use Cases

Implementation Example

// Safe localStorage wrapper
const Storage = {
  get(key, defaultValue = null) {
    try {
      const item = localStorage.getItem(key);
      return item ? JSON.parse(item) : defaultValue;
    } catch (e) {
      console.error('localStorage get error:', e);
      return defaultValue;
    }
  },

  set(key, value) {
    try {
      localStorage.setItem(key, JSON.stringify(value));
      return true;
    } catch (e) {
      console.error('localStorage set error:', e);
      return false;
    }
  },

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

  clear() {
    localStorage.clear();
  }
};

// Usage
Storage.set('theme', 'dark');
const theme = Storage.get('theme', 'light');

Data Serialization

// Always serialize complex types
localStorage.setItem('user', JSON.stringify(user));
const user = JSON.parse(localStorage.getItem('user'));

// Handle dates
const data = {
  createdAt: new Date().toISOString()  // Convert to string
};
localStorage.setItem('data', JSON.stringify(data));
const stored = JSON.parse(localStorage.getItem('data'));
stored.createdAt = new Date(stored.createdAt);  // Convert back

localStorage has several limitations you need to understand.

Limitations

Size Limit

// Check available space
function getStorageSize() {
  let total = 0;
  for (let key in localStorage) {
    if (localStorage.hasOwnProperty(key)) {
      total += localStorage[key].length * 2;  // UTF-16
    }
  }
  return total;
}

try {
  localStorage.setItem('test', 'x'.repeat(5 * 1024 * 1024));
} catch (e) {
  console.error('Storage full:', e.name); // QuotaExceededError
}

Synchronous API

// This blocks the main thread!
localStorage.setItem('large', hugeString);

// Better: Use requestIdleCallback or Web Worker
function saveLargeData(data) {
  requestIdleCallback(() => {
    localStorage.setItem('large', JSON.stringify(data));
  });
}

Cross-Tab Synchronization

// Only syncs via storage event
window.addEventListener('storage', (e) => {
  if (e.key === 'user') {
    const newUser = JSON.parse(e.newValue);
    updateUserUI(newUser);
  }
});

// Does NOT sync in same tab!
// Must use custom events or state management

Alternative: IndexedDB

// For larger, async storage
const request = indexedDB.open('MyDB', 1);

request.onupgradeneeded = (event) => {
  const db = event.target.result;
  db.createObjectStore('users', { keyPath: 'id' });
};

request.onsuccess = (event) => {
  const db = event.target.result;
  const tx = db.transaction('users', 'readwrite');
  const store = tx.objectStore('users');
  store.add({ id: 1, name: 'Alice' });
};

Performance Tips

// Batch operations
const updates = { theme: 'dark', lang: 'en', notifications: true };
Object.entries(updates).forEach(([key, value]) => {
  localStorage.setItem(key, JSON.stringify(value));
});

// Use sessionStorage for temporary data
sessionStorage.setItem('temp', data);

// Use IndexedDB for large datasets
// Use localStorage for small preferences only