shadcn.io is an independent project built on shadcn/ui
useSessionStorage keeps a value under a key in sessionStorage and returns that value, a setter, and a function that deletes the key.
The value lasts until the tab closes. Use it for a draft or for wizard progress you also drive with useStep. In React the first render uses the initial value you passed, then an effect reads what the tab had stored.
Installation
Anatomy
Usage
import { useSessionStorage } from "@/hooks/use-session-storage";const [value, setValue, removeValue] = useSessionStorage("draft", "");setValue takes the next value or a function of the previous one. removeValue deletes the key and restores the initial value.
FAQ
When should I use session storage instead of local storage?
Use session storage when the value should disappear with the tab: a form draft, filters for this visit, or checkout progress. Storage that survives a new visit is a different tool, and it is shared by tabs. Session storage is separate for each tab. Choose it when a second tab must not read or overwrite this tab.
Will the value show up in another tab?
No. Each tab has its own sessionStorage, and a write in one tab does not update another. That is different from local storage, which notifies other tabs. This hook listens for the storage event and for a same-tab session-storage event, so two components in one tab stay aligned. A different tab never sees this value.
Can I store a value that JSON cannot represent?
By default the hook writes JSON.stringify and reads JSON.parse. A Date comes back as a string, and a Map does not survive the trip. Pass serializer and deserializer to convert those yourself. If parsing throws, the hook logs the error and returns the initial value. The stored text undefined is treated as the undefined value.
How do I delete the stored value?
Call the third function the hook returns. It removes the key, sets state back to the initial value, and notifies other hook users in the same tab. Use it for a reset or when someone signs out. Setting state to the initial value without that function leaves the key in place, so a later read would restore the old data.
Is useSessionStorage safe during server rendering?
On the server the hook returns the initial value and does not touch sessionStorage. If initializeWithValue stays true, the client reads storage on the first render and can disagree with the HTML. Pass initializeWithValue false to render the initial value on both sides. The effect then replaces it. A blocked storage API also falls back to the initial value.
Can the initial value be a function?
Yes. You may pass a function the way useState does, and the hook calls it when it needs the default. That result is used when the key is missing, when JSON parsing fails, and when you remove the key. Do not pass a function you meant to store as data. Use the function only as the lazy initial value, and store plain data with the setter.
API Reference
Parameters
keystring
The sessionStorage key.
initialValueT | (() => T)
The value while nothing is stored (or a function that returns it).
- Type
T | (() => T)
options?UseSessionStorageOptions<T>
How the value is turned into a string and back, and when it's first read.
- Type
UseSessionStorageOptions<T>
options.deserializer?(value: string) => T
Turns the stored string back into a value. JSON.parse when left out (and the initial value when that throws).
- Type
(value: string) => T
options.initializeWithValue?boolean
Reads sessionStorage on the first render. false starts from the initial value and reads it after mounting, for markup that must match the server's.
- Default
true
options.serializer?(value: T) => string
Turns the value into the stored string. JSON.stringify when left out.
- Type
(value: T) => string
Returns
[0] valueT
The stored value, or the initial value when nothing is stored.
[1] setValueReact.Dispatch<React.SetStateAction<T>>
Stores a value, or one computed from the current, like useState's setter, and updates every component reading this key. /
- Type
React.Dispatch<React.SetStateAction<T>>
[2] removeValue() => void
Deletes the key from sessionStorage and goes back to the initial value.
- Type
() => void
