@mdus/use-localstorage-hook

A robust, zero-dependency React hook to manage localStorage state with cross-tab synchronization and reactivity.

✨ Features

• 🔄 Cross-Tab Synchronization: Instantly updates state across different browser tabs/windows using the native storage event listener.
• 🛡️ Robust Error Handling: Wrapped in safe try/catch blocks to prevent app crashes if localStorage is disabled, full, or corrupted.
• ⚡ Reactive: Behaves just like useState. Updates trigger immediate re-renders.
• 🔢 Auto-Serialization: Automatically handles JSON.stringify on writes and JSON.parse on reads.
• 🧹 Clean API: Provides intuitive helpers like removeStore and clearAllStore.
• 📦 Zero Dependencies: Lightweight and focused.

📦 Installation

Install the package via your preferred package manager:

# npm
npm install @mdus/use-localstorage-hook

# yarn
yarn add @mdus/use-localstorage-hook

# pnpm
pnpm add @mdus/use-localstorage-hook

💻 Quick Start

Here is a simple example of how to persist a user's theme preference.

import React from 'react';
import useLocalstorage from '@mdus/use-localstorage-hook';

const ThemeSwitcher = () => {
  // Initialize storage with a key and a default value
  const { getStore, setStore, removeStore } = useLocalstorage('app-theme', 'light');

  const toggleTheme = () => {
    const newTheme = getStore === 'light' ? 'dark' : 'light';
    setStore(newTheme);
  };

  return (
    <div style={{ background: getStore === 'light' ? '#fff' : '#333', padding: '20px' }}>
      <h1>Current Theme: {getStore}</h1>
      
      <button onClick={toggleTheme}>
        Toggle Theme
      </button>
      
      <button onClick={removeStore} style={{ marginLeft: '10px' }}>
        Reset to System Default (Remove Key)
      </button>
    </div>
  );
};

export default ThemeSwitcher;

📖 API Reference

useLocalstorage(storeName, initialData)

Parameters

| Parameter | Type | Required | Description | | :--- | :--- | :--- | :--- | | storeName | string | Yes | The unique key used to store data in localStorage. | | initialData | any | Yes | The default value to use if the key does not exist yet. |

Note: If storeName or initialData are missing, the hook will throw an error to prevent silent failures.

Return Object

The hook returns an object containing the current state and utility functions:

| Property | Type | Description | | :--- | :--- | :--- | | getStore | any | The current value of the storage item. Acts like the state variable in useState. | | setStore | (data: any) => void | Updates the state and persists it to localStorage. Accepts any JSON-serializable data. | | removeStore | () => void | Removes the specific key from localStorage and resets state to null. | | clearAllStore | () => void | Caution: Clears all data in localStorage for the domain. |

🛠 Under the Hood

Safety & Error Boundaries

Directly accessing localStorage can be dangerous in modern web development (e.g., inside Iframes, Incognito mode, or when quotas are exceeded). This hook wraps all storage operations in try/catch blocks. If an error occurs (like a JSON parse error), it logs the issue to the console gracefully and falls back to your initialData or null, ensuring your React app doesn't crash.

Cross-Tab Reactivity

The hook attaches an event listener to the window's storage event.

1. When Tab A updates the key 'user_data', the browser fires an event.
2. Tab B catches this event, parses the new value, and updates its local React state immediately.
3. This ensures all open tabs stay in perfect sync without a page reload.