๐๏ธ React hooks for accessing localStorage and sessionStorage, with syncing and prefix support. The complete package.
MIT License
Read the official documentation.
Hooks for easily accessing localStorage
and sessionStorage
, with a similar interface to React.useState()
.
If this project helped you, please consider buying me a coffee or sponsoring me. Your support is much appreciated!
ย
npm i react-storage-complete
Use this hook... | For this Storage API... | Storage Description |
---|---|---|
useLocalStorage | localStorage |
The localStorage object stores data with no expiration date. The data is not deleted when the browser is closed, and is available for future sessions. |
useSessionStorage | sessionStorage |
The sessionStorage object stores data for only one session. The data is deleted when the browser is closed. |
import { useLocalStorage } from 'react-storage-complete';
import { useSessionStorage } from 'react-storage-complete';
Both
useLocalStorage
anduseSessionStorage
share the same interface and are interchangeable.
In your component or hook:
const [name, setName] = useLocalStorage('name');
This will store and retrieve the value using the name
key in localStorage
.
Note: If using TypeScript, you can provide a value type like so:
useLocalStorage<string>('name')
.
You can also provide a default value for when the stored value is undefined
(not currently set in localStorage
):
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.
You can namespace stored items using a prefix:
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
.
With react-storage-complete
, managing stored data for multiple user accounts in the same browser is easy.
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.shouldInitialize
is true
, the prefix is used with the key to retrieve the stored value from localStorage
.initialized
will return as true
, and your value will be ready to use!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.
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.
See the documentation for additional options and uses:
Type definitions have been included for TypeScript support.
Favicon by Twemoji.
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.
If you found this project helpful, let the community know by giving it a star: ๐โญ
See LICENSE.md.