Registry / storage / react-use-localstorage

react-use-localstorage

library3.5.3jsnpmunverified

A React hook that synchronizes state with localStorage. Current version 3.5.3 provides a simple useState-like API with automatic persistence. The library has evolved through breaking changes in v3.0.0 (type changes) and v3.4.0 (cross-tab synchronization). Requires React >=16.8.1. Ships TypeScript types. Key differentiator: minimal abstraction over native localStorage, no dependencies beyond React.

storage

npm install react-use-localstorage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-USE-LOCALSTO

react-use-localstorage

storagejavascriptv3.5.3

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.

useLocalStorage

✓ import useLocalStorage from 'react-use-localstorage'

✗ import { useLocalStorage } from 'react-use-localstorage'

Default export only. Named import will fail. ESM module.

useLocalStorage as any name

✓ import useLocalStorage from 'react-use-localstorage'

✗ const useLocalStorage = require('react-use-localstorage')

CommonJS require works but TypeScript types are better with ESM import.

TypeScript typing for SSR

✓ import type { useLocalStorage } from 'react-use-localstorage'

Type imports supported; types are bundled. For SSR, use a wrapper as shown in README.

Shows basic usage of useLocalStorage hook for persisting a string value to localStorage.

import React from 'react'; import useLocalStorage from 'react-use-localstorage'; function App() { const [name, setName] = useLocalStorage('name', 'Guest'); return <input value={name} onChange={e => setName(e.target.value)} />; } export default App;

Debug

Known issues

breakingsetItem type changed from (item: string) => void to React.Dispatch<string> in v3.0.0

fix

Update any custom types or callbacks expecting (value: string) => void to accept React.Dispatch<string>.

affects: >=3.0.0

breakingReturn type changed to [string, React.Dispatch<React.SetStateAction<string>>] in v3.0.0

fix

Use type inference or update TypeScript definitions accordingly.

affects: >=3.0.0

gotchaSSR: window is not defined. Hook will crash if used during server-side rendering.

fix

Use a wrapper that conditionally calls useLocalStorage only when window is available (see README).

affects: >=1.0.0

gotchaThe hook only supports string values. Non-string values are not serialized.

fix

Manually JSON.stringify/parse values or use a library that supports arbitrary types.

affects: *

deprecatedv3.3.0 reverted to setValue directly setting localStorage instead of via useEffect. Ensure you are on latest patch.

fix

Upgrade to >=3.4.0 to avoid potential stale state issues.

affects: 3.3.0

gotchaCross-tab synchronization added in v3.4.0 may cause unexpected re-renders.

fix

Use a different hook if you want to control synchronization behavior.

affects: >=3.4.0

Errors

Common errors & fixes

Cannot read properties of undefined (reading 'setItem')

Using the hook in a server-side environment where localStorage is unavailable (SSR).

fix

Instantiate only in browser: const useSsrLocalStorage = (key, initial) => typeof window === 'undefined' ? [initial, () => {}] : useLocalStorage(key, initial);

TypeError: (0 , _reactUseLocalstorage.default) is not a function

Trying to use named import instead of default import.

fix

Change import to: import useLocalStorage from 'react-use-localstorage'

Module not found: Can't resolve 'react-use-localstorage'

Package not installed or incorrect path.

fix

Run: npm install react-use-localstorage

Warning: React version mismatch (expected >=16.8.1)

React version below 16.8.1 which is required for hooks.

fix

Update React to >=16.8.1: npm install react@latest react-dom@latest

Upgrade

Version history

3.5.3latest on npm

Audit

Dependencies

reactrequiredpeer dependency required for hooks

Agent activity

19 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/dance2die/react-use-localstorage ↗

packagereact-use-localstorage ↗

homepagehttps://github.com/dance2die/react-use-localstorage ↗