@hamza49/react-local-storage-sync

A small React hook that keeps component state in sync with localStorage, including updates from other tabs.

Install

npm install @hamza49/react-local-storage-sync

Requires React 18 or newer (peer dependency).

Usage

import { useLocalStorageSync } from "@hamza49/react-local-storage-sync";

function Example() {
  const [count, setCount] = useLocalStorageSync("counter", 0);

  return (
    <button type="button" onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

API

useLocalStorageSync<T>(key, initialValue)

• key — localStorage key (string).
• initialValue — used when there is no stored value yet. Values are read and written via JSON.stringify / JSON.parse.

Returns: [value, setValue] — same tuple shape as useState.

If key changes, the hook rebinds to the new key. initialValue is only applied when the store for the current key is first created (e.g. first mount or after a key change).

How it works

Writes go to localStorage and update React state in the current tab. Other tabs receive the native storage event and update subscribers. Same-tab updates use the setter returned from the hook.

Why use this

• One hook, no extra API surface
• Typed with TypeScript
• Cross-tab sync without polling
• ESM package with type declarations

License

ISC