![\"usefy](\"https://raw.githubusercontent.com/mirunamu00/usefy/master/assets/logo.png\"){kind=logo}
\n\n \n
\n A lightweight React hook for persisting state in sessionStorage with automatic same-tab synchronization\n
\n\n\n \n ![\"npm](\"https://img.shields.io/npm/v/@usefy/use-session-storage.svg?style=flat-square&color=007acc\")
\n \n \n ![\"npm](\"https://img.shields.io/npm/dm/@usefy/use-session-storage.svg?style=flat-square&color=007acc\")
\n \n \n ![\"bundle](\"https://img.shields.io/bundlephobia/minzip/@usefy/use-session-storage?style=flat-square&color=007acc\")
![\"license\"](\"https://img.shields.io/npm/l/@usefy/use-session-storage.svg?style=flat-square&color=007acc\")
\n \n
\n Installation ā¢\n Quick Start ā¢\n API Reference ā¢\n Examples ā¢\n License\n
\n\n\n \n š View Storybook Demo\n \n
\n\n---\n\n## Overview\n\n`@usefy/use-session-storage` provides a `useState`-like API for persisting data in sessionStorage. Features include **same-tab component synchronization**, custom serialization, lazy initialization, and error handling. Data persists during the browser session (tab lifetime) but clears when the tab is closed. Each tab has isolated storage, making it perfect for temporary form data, wizard steps, and session-specific state.\n\n**Part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem** ā a collection of production-ready React hooks designed for modern applications.\n\n### Why use-session-storage?\n\n- **Zero Dependencies** ā Pure React implementation with no external dependencies\n- **TypeScript First** ā Full type safety with generics and exported interfaces\n- **useState-like API** ā Familiar tuple return: `[value, setValue, removeValue]`\n- **Same-Tab Sync** ā Multiple components using the same key stay in sync automatically\n- **Tab Isolation** ā Each browser tab has its own session storage\n- **React 18+ Optimized** ā Built with `useSyncExternalStore` for Concurrent Mode compatibility\n- **Auto-Cleanup** ā Data cleared automatically when tab closes\n- **Custom Serialization** ā Support for Date, Map, Set, or any custom type\n- **Lazy Initialization** ā Function initializer support for expensive defaults\n- **Error Handling** ā `onError` callback for graceful error recovery\n- **SSR Compatible** ā Works seamlessly with Next.js, Remix, and other SSR frameworks\n- **Stable References** ā Memoized functions for optimal performance\n- **Well Tested** ā Comprehensive test coverage with Vitest\n\n### localStorage vs sessionStorage\n\n| Feature | localStorage | sessionStorage |\n| ---------------- | ------------------------ | ------------------------- |\n| Data persistence | Until explicitly cleared | Until tab closes |\n| Tab sharing | Shared across all tabs | Isolated per tab |\n| Best for | User preferences, themes | Form drafts, wizard steps |\n\n---\n\n## Installation\n\n```bash\n# npm\nnpm install @usefy/use-session-storage\n\n# yarn\nyarn add @usefy/use-session-storage\n\n# pnpm\npnpm add @usefy/use-session-storage\n```\n\n### Peer Dependencies\n\nThis package requires React 18 or 19:\n\n```json\n{\n \"peerDependencies\": {\n \"react\": \"^18.0.0 || ^19.0.0\"\n }\n}\n```\n\n---\n\n## Quick Start\n\n```tsx\nimport { useSessionStorage } from \"@usefy/use-session-storage\";\n\nfunction CheckoutForm() {\n const [formData, setFormData, clearForm] = useSessionStorage(\n \"checkout-form\",\n {\n name: \"\",\n email: \"\",\n address: \"\",\n }\n );\n\n return (\n \n );\n}\n```\n\n---\n\n## API Reference\n\n### `useSessionStorageStep {step} of 3
\n\n {step === 1 && (\nCart items: {cart.length}
\nThis cart is specific to this tab only
\n \nYou are logged in (this session only)
\n \nQuestion {quiz.currentQuestion + 1} of 10
\n\n Built with care by the usefy team\n
\n","readmeFilename":"README.md"}