Registry / storage / use-storage-state

use-storage-state

library7.0.0jsnpmunverified

React hook for syncing state with any Storage-compatible API (localStorage, sessionStorage, custom). Current stable version is 7.0.0. Actively maintained with frequent releases. Key differentiators: supports SSR, handles cross-tab/window/iframe synchronization via the Window storage event (configurable), compatible with React 18/19 concurrent rendering, and offers a removeItem() reset method. Built-in TypeScript types. Compared to alternatives like react-use/localstorage, this library is focused, lightweight, and production-proven (used by Twitch). Peer dependencies: React >=18 and react-dom >=18.

storage

npm install use-storage-state

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · USE-STORAGE-STATE

use-storage-state

storagejavascriptv7.0.0

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.

useStorageState

✓ import useStorageState from 'use-storage-state'

✗ import { useStorageState } from 'use-storage-state'

This package exports a default export only. Named import will result in undefined.

useStorageState (CommonJS)

✓ const useStorageState = require('use-storage-state')

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

CommonJS require works but destructured named import fails because the default export is used. Use the entire default.

TypeScript import types

✓ import useStorageState from 'use-storage-state' import type { StorageStateOptions } from 'use-storage-state'

✗ import useStorageState, { StorageStateOptions } from 'use-storage-state'

Options type is exported but not as a named export alongside default. Use a separate type import.

Demonstrates useStorageState hook with defaults, React state, and a list. Shows how to persist an array of todos to localStorage.

import React, { useState } from 'react'; import useStorageState from 'use-storage-state'; function Todos() { const [todos, setTodos] = useStorageState('todos', { defaultValue: ['buy avocado', 'do 50 push-ups'] }); const [query, setQuery] = useState(''); function handleAdd() { setQuery(''); setTodos([...todos, query]); } return ( <> <input value={query} onChange={e => setQuery(e.target.value)} /> <button onClick={handleAdd}>Create</button> {todos.map((todo, i) => <div key={i}>{todo}</div>)} </> ); }

Debug

Known issues

gotchaThe hook returns [value, setValue, removeItem] – the third element is a remove function, not a second setter.

fix

Ensure you destructure up to three elements: const [data, setData, remove] = useStorageState(...); remove() clears the stored key and resets to default.

affects: >=7.0.0

breakingVersion 7.0 dropped support for React <18. Older versions (6.x) were compatible with React 16 and 17.

fix

Upgrade to React >=18 or use use-storage-state@6 for older React.

affects: >=7.0.0

gotchaStorage key collisions: using the same key with different default values across components leads to unexpected data.

fix

Use unique keys prefixed by component or feature name (e.g., 'wishlist-todos').

affects: >=0.0.0

deprecatedVersion 6.x had a second argument for setValue that accepted a function to merge with previous state – deprecated in 7.0.

fix

Use functional updates: setTodos(prev => [...prev, newTodo]) instead of passing a merge function.

affects: >=6.0.0 <7.0.0

gotchaSSR hydration may cause double render due to useSyncExternalStore – this is a React behavior, not a bug in the library.

fix

No fix needed; the extra render is expected. Use the `isServerRender` helper from the README if you need to detect.

affects: >=7.0.0

Errors

Common errors & fixes

Cannot destructure property 'useStorageState' of '...' as it is undefined.

Named import used instead of default import.

fix

import useStorageState from 'use-storage-state'

Uncaught TypeError: useStorageState is not a function

Using CommonJS require with destructuring: const { useStorageState } = require('use-storage-state'). The default export is a function, not an object.

fix

const useStorageState = require('use-storage-state')

React 18: useSyncExternalStore is not defined

Using version 7 with React 17 or below.

fix

Upgrade to React >=18 or downgrade to use-storage-state@6.

Warning: useStorageState key "todos" is already in use. Overwriting data.

Two components use the same key 'todos' with different defaults or values.

fix

Ensure each storage key is unique across your app.

Upgrade

Version history

7.0.0latest on npm

Audit

Dependencies

reactrequiredUses React hooks (useSyncExternalStore, useState, useCallback) – peer dependency

react-domrequiredRequired for useSyncExternalStore in React 18 – peer dependency

Agent activity

29 hits · last 30 days

node

Resources

githubhttps://github.com/astoilkov/use-storage-state ↗

packageuse-storage-state ↗

homepagehttps://github.com/astoilkov/use-storage-state ↗