use-session-storage-state

React hook that persist data in sessionStorage

Install

React 18 and above:

1npm install use-session-storage-state

⚠️ React 17 and below. For docs, go to the react-17 branch.

1npm install use-session-storage-state@17

Why

• Clone of use-local-storage-state that I've been actively maintaining for the past 4 years.
• SSR support.
• Works with concurrent rendering and React 19.
• Handles the Window storage event and updates changes across iframe's. Disable with storageSync: false.
• In-memory fallback when sessionStorage throws an error and can't store the data. Provides a isPersistent API to let you notify the user their data isn't currently being stored.
• Aiming for high-quality with my open-source principles.

Usage

1import useSessionStorageState from 'use-session-storage-state'
2
3export default function Todos() {
4    const [todos, setTodos] = useSessionStorageState('todos', {
5        defaultValue: ['buy avocado', 'do 50 push-ups']
6    })
7}

1import React, { useState } from 'react'
2import useSessionStorageState from 'use-session-storage-state'
3
4export default function Todos() {
5    const [todos, setTodos] = useSessionStorageState('todos', {
6        defaultValue: ['buy avocado']
7    })
8    const [query, setQuery] = useState('')
9
10    function onClick() {
11        setQuery('')
12        setTodos([...todos, query])
13    }
14
15    return (
16        <>
17            <input value={query} onChange={e => setQuery(e.target.value)} />
18            <button onClick={onClick}>Create</button>
19            {todos.map(todo => (
20                <div>{todo}</div>
21            ))}
22        </>
23    )
24}
25

1import React, { useState } from 'react'
2import useSessionStorageState from 'use-session-storage-state'
3
4export default function Todos() {
5    const [todos, setTodos, { isPersistent }] = useSessionStorageState('todos', {
6        defaultValue: ['buy avocado']
7    })
8
9    return (
10        <>
11            {todos.map(todo => (<div>{todo}</div>))}
12            {!isPersistent && <span>Changes aren't currently persisted.</span>}
13        </>
14    )
15}
16

1import useSessionStorageState from 'use-session-storage-state'
2
3export default function Todos() {
4    const [todos, setTodos, { removeItem }] = useSessionStorageState('todos', {
5        defaultValue: ['buy avocado']
6    })
7
8    function onClick() {
9        removeItem()
10    }
11}

1function useIsServerRender() {
2  return useSyncExternalStore(() => {
3    return () => {}
4  }, () => false, () => true)
5}

API

useSessionStorageState(key: string, options?: SessionStorageOptions)

Returns [value, setValue, { removeItem, isPersistent }] when called. The first two values are the same as useState(). The third value contains two extra properties:

• removeItem() — calls sessionStorage.removeItem(key) and resets the hook to it's default state
• isPersistent — boolean property that returns false if sessionStorage is throwing an error and the data is stored only in-memory

key

Type: string

The key used when calling sessionStorage.setItem(key) and sessionStorage.getItem(key).

⚠️ Be careful with name conflicts as it is possible to access a property which is already in sessionStorage that was created from another place in the codebase or in an old version of the application.

options.defaultValue

Type: any

Default: undefined

The default value. You can think of it as the same as useState(defaultValue).

options.storageSync

Type: boolean

Default: true

Setting to false doesn't subscribe to the Window storage event. If you set to false, updates won't be synchronized across iframes.

Note: Unlike localStorage, sessionStorage doesn't fire the storage event across tabs and windows.

options.serializer

Type: { stringify, parse }

Default: JSON

JSON does not serialize Date, Regex, or BigInt data. You can pass in superjson or other JSON-compatible serialization library for more advanced serialization.

Related

• use-storage-state — Supports localStorage, sessionStorage, and any other Storage compatible API.
• use-local-storage-state — A clone of this library but for localStorage.
• local-db-storage — Tiny wrapper around IndexedDB that mimics localStorage API.