Registry / storage / use-storage-backed-state

use-storage-backed-state

library2.0.5jsnpmunverified

Custom React hook (v2.0.5) for state management like `useState` but persisted to `localStorage`. Supports `sessionStorage`, custom serializers, and real-time synchronization across tabs via storage events. Requires React 18 or 19. Ships TypeScript types. More lightweight than alternatives like `react-storage-hooks` or `use-persisted-state`, with a focus on simple hook-based API and external get/set/subscribe utilities.

storage

npm install use-storage-backed-state

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · USE-STORAGE-BACKED

use-storage-backed-state

storagejavascriptv2.0.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useStorageBackedState

✓ import { useStorageBackedState } from 'use-storage-backed-state'

✗ import useStorageBackedState from 'use-storage-backed-state'

Named import only; no default export.

getStorageBackedValue

✓ import { getStorageBackedValue } from 'use-storage-backed-state'

✗ const { getStorageBackedValue } = require('use-storage-backed-state')

ESM-only package. Use import syntax.

setStorageBackedValue

✓ import { setStorageBackedValue } from 'use-storage-backed-state'

Can be used outside of React components.

Minimal example of using `useStorageBackedState` with `localStorage` persistence.

import React from 'react'; import { useStorageBackedState } from 'use-storage-backed-state'; function Counter() { const [count, setCount] = useStorageBackedState({ key: 'count', defaultValue: 0, }); return ( <div> <p>Count: {count}</p> <button onClick={() => setCount(count + 1)}>+</button> <button onClick={() => setCount(count - 1)}>-</button> </div> ); }

Debug

Known issues

breakingv2.0.0 changed the hook signature: `useStorageBackedState(key, defaultValue)` became `useStorageBackedState({key, defaultValue, ...})`.

fix

Update calls to use object argument: `useStorageBackedState({ key: 'myKey', defaultValue: 0 })`.

affects: >=1.0.0 <2.0.0

breakingv2.0.0 removed `initialValue` option in favor of `defaultValue`. Using `initialValue` will be ignored or cause TypeScript error.

fix

Replace `initialValue` with `defaultValue`.

affects: >=2.0.0

gotchaThe hook uses `storage` event for cross-tab sync, which fires only in other tabs, not the current one. State updates are immediate within the same tab.

fix

No fix needed; expected behavior.

affects: >=1.0.0

gotchaIf `storage` is explicitly set to `null`, the hook behaves like a regular `useState` without persistence or sync.

fix

Use `storage: null` to opt out of storage.

affects: >=2.0.0

deprecated`initialValue` property was deprecated in v2.0.0 but still accepted with a warning. It will be removed in a future major version.

fix

Use `defaultValue` instead.

affects: >=2.0.0 <3.0.0

Errors

Common errors & fixes

TypeError: Cannot destructure property 'key' of 'undefined' or 'null'

Calling useStorageBackedState without an object argument (v2 only).

fix

useStorageBackedState({ key: 'myKey', defaultValue: 0 })

Warning: `initialValue` is deprecated, use `defaultValue` instead.

Using `initialValue` property in v2.

fix

Replace `initialValue` with `defaultValue`.

Module not found: Can't resolve 'use-storage-backed-state'

Package not installed.

fix

npm install use-storage-backed-state

Upgrade

Version history

2.0.5latest on npm

Audit

Dependencies

reactrequiredpeer dependency; required to use the hook

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/FilipChalupa/use-storage-backed-state ↗

packageuse-storage-backed-state ↗

homepagehttps://github.com/FilipChalupa/use-storage-backed-state#readme ↗