README
react-hook-session-web-storage :anchor:
A React hook to access sessionStorage
.
Installation
Using npm
:
npm install react-hook-session-web-storage
Using yarn
:
yarn add react-hook-session-web-storage
Basic usage
The useSessionStorage
hook, similarly to the useState
hook, returns an array of two elements:
The first element contains the value stored in
sessionStorage
.The second element is a function which can be called with a value which will be converted to string and stored in
sessionStorage
. If this function is called without an argument, or with the argumentnull
orundefined
, thesessionStorage
entry will be removed.
The key to the sessionStorage
entry you want to access must be supplied to the hook as its first argument.
For example:
import useSessionStorage from "react-hook-session-web-storage";
const ComponentWithSessionStorage = () => {
const [value, setValue] = useSessionStorage("myKey");
return (
<div>
<p>Value in SessionStorage: {value}</p>
<button
onClick={() => {
setValue("Value from hook");
}}
>
Set myKey
</button>
<button
onClick={() => {
setValue(null);
}}
>
Unset myKey
</button>
</div>
);
};
sessionStorage
entires
Using multiple The useSessionStorage
hook can work with multiple sessionStorage
entries simultaneously.
In order to achieve this, the first argument specified when calling the hook must be an object instead of a string. The keys of the object will represent the sessionStorage
entry keys used by the hook. The values specified in this object will be ignored, in order to avoid confusion, it is recommended to use null
as values.
If the useSessionStorage
hook is called like this, the array it returns will contain two elements:
The first element is an object which contains all values in the
sessionStorage
by the keys specified in the object the hook was called with.The second element is a function which expects an object as a parameter, in which the keys must be a subset of the keys of the object the hook was called with. Every
sessionStorage
entry corresponding to a key in this object will be set to the value specified by that key (converted to string). If the value by any key isnull
orundefined
, the correspondingsessionStorage
entry will be unset.
For example:
import useSessionStorage from "react-hook-session-web-storage";
const ComponentWithSessionStorage = () => {
const [values, setValues] = useSessionStorage({
myKey: null,
myOtherKey: null,
});
const { myKey, myOtherKey } = values;
return (
<div>
<p>
Values in SessionStorage: {myKey}, {myOtherKey}
</p>
<button
onClick={() => {
setValues({ myKey: "Setting myKey from hook" });
}}
>
Set myKey, leave myOtherKey intact
</button>
<button
onClick={() => {
setValues({ myOtherKey: "Setting myOtherKey from hook" });
}}
>
Set myOtherKey, leave myKey intact
</button>
<button
onClick={() => {
setValues({
myKey: "Setting myKey from hook",
myOtherKey: "Setting myOtherKey from hook",
});
}}
>
Set both myKey and myOtherKey
</button>
<button
onClick={() => {
setValues({
myKey: null,
});
}}
>
Unset myKey, leave myOtherKey intact
</button>
<button
onClick={() => {
setValues({
myOtherKey: null,
});
}}
>
Unset myOtherKey, leave myKey intact
</button>
<button
onClick={() => {
setValues({
myKey: "Setting myKey from hook",
myOtherKey: null,
});
}}
>
Set myKey and unset myOtherKey
</button>
<button
onClick={() => {
setValues({
myKey: null,
myOtherKey: null,
});
}}
>
Unset both myKey and myOtherKey
</button>
</div>
);
};
Enable syncing
By default sessionStorage
will be accessed only once when the component using the hook is mounted.
The hook can be configured to automatically react to changes of the sessionStorage
entry or entries by calling it with a second options
parameter, in which by the key syncFrequency
the frequency of reading the data from sessionStorage
can be specified in milliseconds.
This feature works the same way whether the hook is used with a single sessionStorage
entry or multiple entires.
For example:
import useSessionStorage from "react-hook-session-web-storage";
const ComponentWithSessionStorage = () => {
const [value, setValue] = useSessionStorage("myKey", { syncFrequency: 1000 });
return (
<div>
<p>Value in SessionStorage: {value}</p>
<button
onClick={() => {
setValue("Value from hook");
}}
>
Set value with hook
</button>
<button
onClick={() => {
setValue(null);
}}
>
Unset value
</button>
</div>
);
};
Be aware that when the hook is used like this, the component will access sessionStorage
at regular intervals, which can result in a delay in registering changes and lead to performance issues if the update frequency is low.
Limitations
sessionStorage
is using the Storage interface of the Web Storage API which requires all keys and values to be strings.
Migrating from 1.x.x
If you were using default import, remember to specify the syncFrequency
in the second options
parameter when calling the hook to keep syncing with sessionStorage
.
If you were using the named import useSessionStorageNoSync
, simply switch to default import.
Contributions
Contributions are welcome. File bug reports, create pull requests, feel free to reach out at tothab@gmail.com.
License
react-hook-session-web-storage
is licensed under LGPL.