@guoyunhe/react-storage

@guoyunhe/react-storage

React hooks for localStorage and sessionStorage — JSON serialization, custom serializer/parser, key prefix namespacing, and real-time cross-tab sync. SSR-safe with zero direct dependencies.

Features

• 🪝 useState-like API — drop-in replacement with the same [value, setValue] tuple
• 🔄 Cross-tab sync — state stays in sync across browser tabs via the native storage event
• 🧩 Custom serializer/parser — store Date, Map, or any custom type
• 📦 JSON by default — objects and arrays work out of the box
• 🏷️ Key prefix — namespace storage keys per app via <StorageProvider>
• 🌐 SSR-safe — no window access during render, works with Next.js and Remix
• 🪶 Tiny bundle — zero runtime dependencies, tree-shakable ESM
• 💪 TypeScript first — fully typed with generics

Install

npm install --save @guoyunhe/react-storage

Quick Start

import { useLocalStorage, useSessionStorage } from '@guoyunhe/react-storage';

function App() {
  const [settings, setSettings] = useLocalStorage('settings', {
    theme: 'dark',
    fontSize: 14,
  });

  const [draft, setDraft] = useSessionStorage('draft', '');
}

Guides

Custom types (Date, Map, etc.)

Use serializer and parser to handle non-JSON types:

const [date, setDate] = useLocalStorage('date', new Date(), {
  serializer: (d) => d.toISOString(),
  parser: (s) => new Date(s),
});

Key prefix for multi-app domains

Scope storage keys per app to avoid collisions:

import { StorageProvider, useLocalStorage } from '@guoyunhe/react-storage';

function App() {
  return (
    <StorageProvider prefix='dashboard_'>
      <Dashboard />
    </StorageProvider>
  );
}

function Dashboard() {
  // actual key: "dashboard_theme"
  const [theme, setTheme] = useLocalStorage('theme', 'light');
}

Global serializer/parser

Set defaults once at the top level:

<StorageProvider serializer={mySerializer} parser={myParser} prefix='app_'>
  <App />
</StorageProvider>

Cross-tab counter

All components reading the same key stay in sync — even across tabs:

function Counter() {
  const [count, setCount] = useLocalStorage('count', 0);

  return (
    <div>
      <button onClick={() => setCount((c) => c - 1)}>−</button>
      <span>{count}</span>
      <button onClick={() => setCount((c) => c + 1)}>+</button>
    </div>
  );
}

// Render multiple <Counter /> — they all share the same state

API

useLocalStorage<T>(key, defaultValue, options?)

Returns [value, setValue] — same shape as useState. Values persist in localStorage and sync across tabs.

useSessionStorage<T>(key, defaultValue, options?)

Same API as useLocalStorage, but stores in sessionStorage. Data is cleared when the tab closes. Useful for draft forms, wizard state, and ephemeral UI state.

options

Option	Type	Default	Description
serializer	(value: T) => string	JSON.stringify	Custom serialize function
parser	(raw: string) => T	JSON.parse	Custom parse function
prefix	string	''	Override the global prefix for this key

<StorageProvider>

Provides global defaults for all hooks within its subtree.

Prop	Type	Default	Description
serializer	(value: any) => string	JSON.stringify	Global serializer
parser	(raw: string) => any	JSON.parse	Global parser
prefix	string	''	Global key prefix

Comparison

	@guoyunhe/react-storage	use-local-storage-state	usehooks-ts	react-use	ahooks
React peer	>=16.8	>=18	>=16.8	*	>=16.8
Dependencies	0	0	1	14	10
Local + Session	✅	❌	✅	✅	✅
Cross-tab sync	✅	✅	❌	❌	✅
Key prefix	✅	❌	❌	❌	❌
Custom serializer	✅	✅	✅	❌	✅
Typed API	✅	✅	✅	✅	✅
ESM	✅	✅	✅	✅	✅

License

MIT