\n );\n};\n\nexport default Demo;\n```\n\n## 🛠️ API\n\n### Parameters\n\n```typescript\ntype useUrlStorageStateParams = {\n key: string; // URL parameter and storage key\n defaultValue: T; // Default value if none exists\n prefix?: string; // Optional storage key prefix (default: current pathname)\n storage?: Storage; // Optional storage type (default: localStorage)\n previousKeys?: string[]; // Old keys to remove from storage on mount\n};\n```\n\n### Returns\n\n```typescript\n[T, (newValue: T | ((prev: T) => T)) => void]\n```\n\n- `T`: The current state value.\n- `(newValue: T | ((prev: T) => T)) => void`: A function to update the state.\n\n## 🔧 Usage Examples\n\n### Basic Usage\n\n```tsx\nimport { useUrlStorageState } from 'use-url-storage-state';\n\nconst [filters, setFilters] = useUrlStorageState({\n key: 'filters',\n defaultValue: { search: '', category: 'all' },\n});\n\n// URL: http://localhost:3000/?filters={\"search\":\"\",\"category\":\"all\"}\n// Storage: urlStorage_/current_pathname_filters\n```\n\n### With Custom Prefix\n\nUsing a shared prefix is useful when you want states across different paths or to share the same logical grouping in storage. For example, you might want all multiple pages to affect and persist the same url params:\n\n```tsx\nimport { useUrlStorageState } from 'use-url-storage-state';\n\nconst [filters, setFilters] = useUrlStorageState({\n key: 'filters',\n defaultValue: { search: '', category: 'all' },\n prefix: 'somePrefix',\n});\n\n// URL: http://localhost:3000/?filters={\"search\":\"\",\"category\":\"all\"}\n// Storage: somePrefix_filters\n```\n\n### Default Prefix as Pathname\n\nBy default, the prefix is set to the current `location.pathname`. This ensures that states are unique to each page in your application. For instance, if you navigate from `/home` to `/profile`, the storage keys will differ:\n\n- `/home`: `urlStorage_/home_filters`\n- `/profile`: `urlStorage_/profile_filters`\n\nThis behavior prevents cross-page conflicts and keeps the state isolated to its corresponding route.\n\n### Using Session Storage\n\n```tsx\nimport { useUrlStorageState } from 'use-url-storage-state';\n\nconst [sessionState, setSessionState] = useUrlStorageState({\n key: 'userSession',\n defaultValue: { loggedIn: false },\n storage: sessionStorage,\n});\n```\n\n### Managing Multiple States\n\n```tsx\nimport { useUrlStorageState } from 'use-url-storage-state';\n\nconst [filters, setFilters] = useUrlStorageState({\n key: 'filters',\n defaultValue: { search: '', category: 'all' },\n});\n\nconst [theme, setTheme] = useUrlStorageState({\n key: 'theme',\n defaultValue: { darkMode: false },\n});\n```\n\n### Cleaning Up Old Storage Keys\n\nWhen you rename a key, pass the old names via `previousKeys` to remove stale storage entries on mount:\n\n```tsx\nimport { useUrlStorageState } from 'use-url-storage-state';\n\nconst [filters, setFilters] = useUrlStorageState({\n key: 'search_filters',\n defaultValue: { search: '', category: 'all' },\n previousKeys: ['filters', 'old_filters'], // removed from storage on mount\n});\n```\n\n## 📝 Notes\n\n1. URL parameters are always strings, so complex objects are automatically serialized/deserialized\n2. The hook maintains sync between URL and storage.\n - If a URL parameter exists, it will update the storage\n - If a storage value exists, and no URL parameter exists, it will update the URL\n - If none exists, it will populate the URL and storage with the default value\n3. The default state will populate the URL and storage if none exists automatically\n4. The hook will only refer to queryParams that exists in state, and will ignore any other query params\n\n## 📦 useStorage Hook\n\n### 🌟 Overview\n\nThe `useStorage` hook is a low-level utility for interacting with browser storage (e.g., `localStorage`, `sessionStorage`). It provides reactive state management tied to storage keys, making it easy to persist and retrieve data.\n\n### 🚀 Features\n\n- **Custom Serialization**: Allows for custom serialization and deserialization of storage values.\n- **Live Synchronization**: Keeps state synchronized across tabs.\n- **Default Value Initialization**: Initializes storage keys with default values.\n\n### 🛠️ API\n\n#### Parameters\n\n```typescript\ntype StorageProps = {\n key: string; // The storage key.\n defaultValue: ValueType; // Default value if no value exists.\n storage?: Storage; // Storage type (localStorage/sessionStorage). Default: localStorage.\n live?: boolean; // Synchronize across tabs. Default: false.\n serialize?: (value: ValueType) => string; // Custom serialization function. Default: JSON.stringify.\n deserialize?: (str: string) => ValueType; // Custom deserialization function. Default: JSON.parse.\n forceInit?: (value?: string) => boolean; // Force initialization logic. Default: never.\n previousKeys?: string[]; // Old keys to remove from storage on mount.\n};\n```\n\n#### Returns\n\n```typescript\n[ValueType, (newValue: ValueType | ((prev: ValueType) => ValueType)) => void]\n```\n\n### 🔧 Usage Examples\n\n#### Basic Usage\n\n```tsx\nimport { useStorage } from 'use-url-storage-state';\n\nconst [value, setValue] = useStorage({\n key: 'myKey',\n defaultValue: 'defaultValue',\n});\n\nsetValue('newValue');\n```\n\n#### Custom Serialization\n\n```tsx\nimport { useStorage } from 'use-url-storage-state';\n\nconst [user, setUser] = useStorage({\n key: 'user',\n defaultValue: { name: 'Guest' },\n serialize: (value) => btoa(JSON.stringify(value)),\n deserialize: (str) => JSON.parse(atob(str)),\n});\n```\n\n#### Live Synchronization\n\n```tsx\nimport { useStorage } from 'use-url-storage-state';\n\nconst [theme, setTheme] = useStorage({\n key: 'theme',\n defaultValue: 'light',\n live: true,\n});\n```\n\n#### Using `forceInit` for Conditional Initialization\n\n```tsx\nimport { useStorage } from 'use-url-storage-state';\n\nconst [count, setCount] = useStorage({\n key: 'counter',\n defaultValue: 0,\n forceInit: (existingValue) =>\n existingValue === undefined || existingValue === null,\n});\n\n// The key will be initialized to 0 only if it doesn't exist or is null.\nsetCount((prev) => prev + 1);\n```\n\n#### Specifying `sessionStorage` Instead of `localStorage`\n\n```tsx\nimport { useStorage } from 'use-url-storage-state';\n\nconst [sessionData, setSessionData] = useStorage({\n key: 'sessionKey',\n defaultValue: 'sessionValue',\n storage: sessionStorage,\n});\n\nsetSessionData('newSessionValue');\n```\n\n### 📝 Notes\n\n1. **Storage Type**: The default storage is `localStorage`. If you need ephemeral data that clears on browser close, use `sessionStorage` by setting the `storage` option.\n2. **Custom Serialization**: Use `serialize` and `deserialize` when working with complex objects, or when you need encrypted or encoded storage.\n3. **Live Synchronization**: Enable the `live` option for use cases that require real-time updates across browser tabs or windows, like theme synchronization or shared state.\n4. **Force Initialization**: The `forceInit` function is useful for cases where existing values might be invalid or require resetting.\n\n## 📜 License\n\nThis project is licensed under the MIT License\n\n## 🎉 Acknowledgments\n\n- Inspired by Kent C. Dodds, https://www.youtube.com/watch?v=yu3dnHrnps4\n- Special thanks to [Idan Entin](https://github.com/idanen)\n","readmeFilename":"README.md"}