🗄️ React Storage Complete

React hooks for accessing localStorage and sessionStorage, with syncing and prefix support. The complete package.

('name')`. #### Providing A Default Value You can also provide a default value for when the stored value is `undefined` (not currently set in `localStorage`): ```jsx const [name, setName] = useLocalStorage('name', 'Guest'); ``` In this example, when the stored item with the key `name` is `undefined`, the `name` value will be `Guest`. > Note: When a value is `null` in storage, `null` is returned, not the provided default. #### Namespacing Using Prefix You can namespace stored items using a prefix: ```jsx const [name, setName] = useLocalStorage('name', 'Guest', { prefix: 'my-namespace', }); ``` For example, by using a user ID as the prefix, you can scope the stored data to the user and avoid mixing settings. Above, the key for the value would be `my-namespace.name`. ##### Namespacing Using User IDs With `react-storage-complete`, managing stored data for multiple user accounts in the same browser is easy. ```jsx const [name, setName, initialized] = useLocalStorage('name', 'Guest', { prefix: user?.id, // Undefined until user ID is available as a namespace shouldInitialize: !!user?.id, // Only initialize when user ID is available }); ``` As shown above, you can delay initialization of the stored value until your prefix is available and ready to use as the namespace. For example, a user ID may not be ready until logged in, but you may still be calling the hook in your app before that happens. In this example: - `initialized` will be `false` until the `user.id` is loaded and ready to use as the prefix. - When `shouldInitialize` is `true`, the prefix is used with the key to retrieve the stored value from `localStorage`. - Then, `initialized` will return as `true`, and your value will be ready to use! #### Clearing The Value ```jsx const [name, setName, initialized, clear] = useLocalStorage('name', 'Guest'); ``` You can clear any stored value and completely remove it from storage using the returned clear function. In this example, calling `clear()` will delete the item from storage. You can also call `setName(undefined)` to achieve the same result. #### Accessing The Prefixed Key ```jsx const [food, setFood, initialized, clear, prefixedKey] = useLocalStorage('food', 'Hamburger', { prefix: 'my-namespace', }); ``` The hook also returns the prefixed key, in case you want direct access to it. In the example above, the prefixed key would be `my-namespace.food`. > You can customize the separator by providing the `prefixSeparator` option. #### Additional Options & Uses See the documentation for additional options and uses: - [useLocalStorage documentation](https://justinmahar.github.io/react-storage-complete/?path=/story/hooks-uselocalstorage--docs) - [useSessionStorage documentation](https://justinmahar.github.io/react-storage-complete/?path=/story/hooks-usesessionstorage--docs) ## TypeScript Type definitions have been included for [TypeScript](https://www.typescriptlang.org/) support. ## Icon Attribution Favicon by [Twemoji](https://github.com/twitter/twemoji). ## Contributing Open source software is awesome and so are you. 😎 Feel free to submit a pull request for bugs or additions, and make sure to update tests as appropriate. If you find a mistake in the docs, send a PR! Even the smallest changes help. For major changes, open an issue first to discuss what you'd like to change. ## ⭐ Found It Helpful? [Star It!](https://github.com/justinmahar/react-storage-complete/stargazers) If you found this project helpful, let the community know by giving it a [star](https://github.com/justinmahar/react-storage-complete/stargazers): [👉⭐](https://github.com/justinmahar/react-storage-complete/stargazers) Want to support the project? Feel free to grab me a coffee, which is my main source of fuel for development:     ## License See [LICENSE.md](https://justinmahar.github.io/react-storage-complete/?path=/docs/license--docs).