Browser Storage: localStorage, sessionStorage, and IndexedDB

Browser storage options serve different needs. Here's how to choose and use each effectively.

Storage Comparison#

| Feature        | Cookies      | localStorage | sessionStorage | IndexedDB    |
|----------------|--------------|--------------|----------------|--------------|
| Capacity       | 4KB          | 5-10MB       | 5-10MB         | 50MB+        |
| Persistence    | Configurable | Permanent    | Tab session    | Permanent    |
| Sent to server | Yes          | No           | No             | No           |
| Sync/Async     | Sync         | Sync         | Sync           | Async        |
| Data type      | String       | String       | String         | Any          |

localStorage#

// Simple key-value storage
localStorage.setItem('theme', 'dark');
const theme = localStorage.getItem('theme');
localStorage.removeItem('theme');
localStorage.clear();

// Store objects (must serialize)
const user = { id: '123', name: 'John' };
localStorage.setItem('user', JSON.stringify(user));
const stored = JSON.parse(localStorage.getItem('user') || 'null');

// Type-safe wrapper
class LocalStorage<T> {
  constructor(private key: string) {}

  get(): T | null {
    const item = localStorage.getItem(this.key);
    return item ? JSON.parse(item) : null;
  }

  set(value: T): void {
    localStorage.setItem(this.key, JSON.stringify(value));
  }

  remove(): void {
    localStorage.removeItem(this.key);
  }
}

// Usage
const userStorage = new LocalStorage<User>('user');
userStorage.set({ id: '123', name: 'John' });
const user = userStorage.get();

// Listen for changes (cross-tab)
window.addEventListener('storage', (event) => {
  if (event.key === 'user') {
    console.log('User changed:', event.newValue);
  }
});

sessionStorage#

// Same API as localStorage, but per-tab
sessionStorage.setItem('formDraft', JSON.stringify(formData));
const draft = JSON.parse(sessionStorage.getItem('formDraft') || '{}');

// Good for:
// - Form data preservation during session
// - Temporary state
// - Tab-specific data

// React hook for sessionStorage
function useSessionStorage<T>(key: string, initialValue: T) {
  const [value, setValue] = useState<T>(() => {
    const stored = sessionStorage.getItem(key);
    return stored ? JSON.parse(stored) : initialValue;
  });

  useEffect(() => {
    sessionStorage.setItem(key, JSON.stringify(value));
  }, [key, value]);

  return [value, setValue] as const;
}

// Usage
function CheckoutForm() {
  const [formData, setFormData] = useSessionStorage('checkout', {
    name: '',
    address: '',
  });

  // Form preserved if user refreshes
}

IndexedDB#

// Async database for large/complex data
class Database {
  private db: IDBDatabase | null = null;
  private dbName: string;
  private version: number;

  constructor(dbName: string, version: number = 1) {
    this.dbName = dbName;
    this.version = version;
  }

  async open(): Promise<void> {
    return new Promise((resolve, reject) => {
      const request = indexedDB.open(this.dbName, this.version);

      request.onerror = () => reject(request.error);
      request.onsuccess = () => {
        this.db = request.result;
        resolve();
      };

      request.onupgradeneeded = (event) => {
        const db = (event.target as IDBOpenDBRequest).result;

        // Create object stores
        if (!db.objectStoreNames.contains('users')) {
          db.createObjectStore('users', { keyPath: 'id' });
        }

        if (!db.objectStoreNames.contains('posts')) {
          const store = db.createObjectStore('posts', { keyPath: 'id' });
          store.createIndex('userId', 'userId', { unique: false });
          store.createIndex('createdAt', 'createdAt', { unique: false });
        }
      };
    });
  }

  async add<T>(storeName: string, data: T): Promise<void> {
    return new Promise((resolve, reject) => {
      const transaction = this.db!.transaction(storeName, 'readwrite');
      const store = transaction.objectStore(storeName);
      const request = store.add(data);

      request.onerror = () => reject(request.error);
      request.onsuccess = () => resolve();
    });
  }

  async get<T>(storeName: string, key: string): Promise<T | undefined> {
    return new Promise((resolve, reject) => {
      const transaction = this.db!.transaction(storeName, 'readonly');
      const store = transaction.objectStore(storeName);
      const request = store.get(key);

      request.onerror = () => reject(request.error);
      request.onsuccess = () => resolve(request.result);
    });
  }

  async getAll<T>(storeName: string): Promise<T[]> {
    return new Promise((resolve, reject) => {
      const transaction = this.db!.transaction(storeName, 'readonly');
      const store = transaction.objectStore(storeName);
      const request = store.getAll();

      request.onerror = () => reject(request.error);
      request.onsuccess = () => resolve(request.result);
    });
  }

  async put<T>(storeName: string, data: T): Promise<void> {
    return new Promise((resolve, reject) => {
      const transaction = this.db!.transaction(storeName, 'readwrite');
      const store = transaction.objectStore(storeName);
      const request = store.put(data);

      request.onerror = () => reject(request.error);
      request.onsuccess = () => resolve();
    });
  }

  async delete(storeName: string, key: string): Promise<void> {
    return new Promise((resolve, reject) => {
      const transaction = this.db!.transaction(storeName, 'readwrite');
      const store = transaction.objectStore(storeName);
      const request = store.delete(key);

      request.onerror = () => reject(request.error);
      request.onsuccess = () => resolve();
    });
  }
}

// Usage
const db = new Database('myApp', 1);
await db.open();

await db.add('users', { id: '123', name: 'John', email: 'john@example.com' });
const user = await db.get('users', '123');
const allUsers = await db.getAll('users');

Cookies#

// Set cookie
document.cookie = 'theme=dark; path=/; max-age=31536000; secure; samesite=strict';

// Parse cookies
function getCookie(name: string): string | null {
  const match = document.cookie.match(new RegExp(`(^| )${name}=([^;]+)`));
  return match ? decodeURIComponent(match[2]) : null;
}

// Set cookie helper
function setCookie(
  name: string,
  value: string,
  options: {
    maxAge?: number;
    expires?: Date;
    path?: string;
    domain?: string;
    secure?: boolean;
    sameSite?: 'strict' | 'lax' | 'none';
  } = {}
): void {
  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;

  if (options.maxAge) cookie += `; max-age=${options.maxAge}`;
  if (options.expires) cookie += `; expires=${options.expires.toUTCString()}`;
  if (options.path) cookie += `; path=${options.path}`;
  if (options.domain) cookie += `; domain=${options.domain}`;
  if (options.secure) cookie += '; secure';
  if (options.sameSite) cookie += `; samesite=${options.sameSite}`;

  document.cookie = cookie;
}

// Delete cookie
function deleteCookie(name: string): void {
  document.cookie = `${name}=; max-age=0; path=/`;
}

// Usage
setCookie('session', 'abc123', {
  maxAge: 86400,
  path: '/',
  secure: true,
  sameSite: 'strict',
});

When to Use What#

// localStorage: Persistent user preferences
localStorage.setItem('theme', 'dark');
localStorage.setItem('language', 'en');

// sessionStorage: Temporary form data
sessionStorage.setItem('checkoutStep', '2');
sessionStorage.setItem('cartItems', JSON.stringify(items));

// IndexedDB: Large datasets, offline data
await db.add('articles', { id: '1', content: '...', images: [...] });

// Cookies: Auth tokens, server-readable data
setCookie('auth_token', token, { secure: true, sameSite: 'strict' });

Storage with Expiration#

interface StorageItem<T> {
  value: T;
  expiry: number;
}

class ExpiringStorage<T> {
  constructor(private key: string) {}

  set(value: T, ttlMs: number): void {
    const item: StorageItem<T> = {
      value,
      expiry: Date.now() + ttlMs,
    };
    localStorage.setItem(this.key, JSON.stringify(item));
  }

  get(): T | null {
    const itemStr = localStorage.getItem(this.key);
    if (!itemStr) return null;

    const item: StorageItem<T> = JSON.parse(itemStr);

    if (Date.now() > item.expiry) {
      localStorage.removeItem(this.key);
      return null;
    }

    return item.value;
  }
}

// Usage
const cache = new ExpiringStorage<User[]>('cachedUsers');
cache.set(users, 60 * 60 * 1000); // 1 hour
const cached = cache.get(); // null if expired

Best Practices#

Security:
✓ Never store sensitive data unencrypted
✓ Use httpOnly cookies for auth tokens
✓ Set appropriate cookie flags
✓ Validate stored data

Performance:
✓ Don't store too much in localStorage
✓ Use IndexedDB for large data
✓ Batch IndexedDB operations
✓ Clean up expired data

Reliability:
✓ Handle storage quota errors
✓ Provide fallbacks
✓ Validate JSON parsing
✓ Test private browsing mode

Choose storage based on data size, persistence needs, and whether the server needs access. localStorage for small persistent data, sessionStorage for tab-specific temporary data, IndexedDB for large datasets, and cookies when the server needs the data.