useLocalStorage

A React hook for interacting with browser localStorage.

Installation

npm install @plenty-hooks/use-local-storage

Usage

import useLocalStorageValue, { useLocalStorage } from '@plenty-hooks/use-local-storage';

// Basic usage with useLocalStorage (no React state sync)
function SettingsComponent() {
  const storage = useLocalStorage({ json: true });

  const saveSettings = () => {
    storage.setItem('theme', 'dark');
    storage.setItem('notifications', { email: true, push: false });
  };

  const loadSettings = () => {
    const theme = storage.getItem<string>('theme');
    const notifications = storage.getItem<{ email: boolean; push: boolean }>('notifications');
    console.log(theme, notifications);
  };

  return (
    <div>
      <button onClick={saveSettings}>Save Settings</button>
      <button onClick={loadSettings}>Load Settings</button>
    </div>
  );
}

// Usage with useLocalStorageValue (React state synchronized)
function UserComponent() {
  const { value, setValue, removeValue } = useLocalStorageValue<string>('username');

  return (
    <div>
      <p>Username: {value ?? 'Not set'}</p>
      <button onClick={() => setValue('john_doe')}>Set Username</button>
      <button onClick={removeValue}>Clear Username</button>
    </div>
  );
}

API

useLocalStorage(options?: LocalStorageOptions)

Returns a localStorage interface with methods to interact with browser storage. This hook does NOT synchronize values with React state. If you need React state synchronization, use useLocalStorageValue instead.

Parameters

• options (optional): Configuration object with the following properties:
  • prefix?: string - Prefix to add to all storage keys
  • json?: boolean - Whether to automatically serialize/deserialize values as JSON

Returns

An object containing:

• setItem: <T>(key: string, value: T) => void - Stores a value in localStorage
• getItem: <T>(key: string) => T | null - Retrieves a value from localStorage
• removeItem: (key: string) => void - Removes a value from localStorage
• clear: () => void - Clears all values (or all with prefix if configured)

useLocalStorageValue<T>(key: string, options?: LocalStorageOptions)

Manages a single local storage value with automatic synchronization across tabs. The value is synchronized with React state, causing components to re-render when it changes.

Parameters

• key: string - The storage key (will be prefixed if a prefix is configured)
• options (optional): Configuration object with the following properties:
  • prefix?: string - Prefix to add to the storage key
  • json?: boolean - Whether to serialize/deserialize the value as JSON

Returns

An object containing:

• value: T | null - Current value (synced with React state)
• setValue: (value: T) => void - Updates the value in localStorage
• removeValue: () => void - Removes the value from localStorage

configureLocalStorage(options: LocalStorageOptions)

Configures global options for all local storage operations.

Parameters

• options: Configuration object with the following properties:
  • prefix?: string - Prefix to add to all storage keys
  • json?: boolean - Whether to automatically serialize/deserialize values as JSON