npm package: @plenty-hooks/use-local-storage
Description: A React hook for interacting with browser localStorage.
Latest version: 1.24.2

# useLocalStorage

A React hook for interacting with browser localStorage.

## Installation

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

## Usage

```tsx
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