Registry / storage / use-local-storage

use-local-storage

library3.0.0jsnpmunverified

A flexible React Hook for persisting state to localStorage, with an API similar to React's useState. Version 3.0.0 supports React >=16.8.1, TypeScript types, SSR, and cross-tab synchronization. It uses JSON.stringify/JSON.parse by default but allows custom serializers, parsers, and error loggers. Key differentiators: automatic cross-context sync, type inference, and the ability to remove a key by setting its value to undefined. Released under MIT, actively maintained.

storage

npm install use-local-storage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · USE-LOCAL-STORAGE

use-local-storage

storagejavascriptv3.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.

useLocalStorage

✓ import useLocalStorage from 'use-local-storage'

✗ const { useLocalStorage } = require('use-local-storage')

This package is ESM-only with a default export. CommonJS require will fail. Use default import syntax.

useLocalStorage (types)

✓ import useLocalStorage from 'use-local-storage'

✗ import { useLocalStorage } from 'use-local-storage'

TypeScript users often mistakenly use a named import. The correct import is the default export.

useLocalStorage (with generic)

✓ const [value, setValue] = useLocalStorage<string>('key')

✗ const [value, setValue] = useLocalStorage<string>('key', '')

Passing a default value as second argument will infer the type; using a generic is optional but allows stricter typing.

Demonstrates basic usage with a numeric default value, incrementing, and removing the localStorage key by setting undefined.

import useLocalStorage from 'use-local-storage'; function App() { const [count, setCount] = useLocalStorage('count', 0); return ( <div> <p>Count: {count}</p> <button onClick={() => setCount(count + 1)}>Increment</button> <button onClick={() => setCount(undefined)}>Remove</button> </div> ); }

Debug

Known issues

breakingIn version 3.0.0, the default import changed to a named export was never introduced; but type definitions were added and import path remains the same. Ensure to use default import syntax.

fix

Use `import useLocalStorage from 'use-local-storage'` instead of any other import pattern.

affects: >=3.0.0

deprecatedSetting a value to undefined removes the localStorage key. This is intended behavior but can be surprising if you expect undefined to be stored as the string 'undefined'.

fix

If you want to store the literal value undefined, use JSON.stringify(undefined) manually or custom serializer.

affects: >=1.0.0

gotchaThe hook uses `JSON.parse` by default. If you store non-JSON-serializable data (e.g., `Date`), it will be serialized as a string and not automatically deserialized back.

fix

Provide a custom serializer/parser in the options object to handle non-standard types.

affects: >=1.0.0

gotchaCross-tab synchronization is enabled by default. If you have multiple tabs open, changes in one tab will update the state in others. This might cause unexpected re-renders.

fix

Set `syncData: false` in options to disable cross-tab sync.

affects: >=2.0.0

gotchaThe hook throws if localStorage is not available (e.g., in private browsing or some SSR scenarios). It will catch the error and log it via console.error by default, but you can provide a custom logger.

fix

Initialize with a fallback value or wrap in try-catch, but the hook already catches internally.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'use-local-storage' or its corresponding type declarations

TypeScript not configured to resolve node_modules or missing @types/use-local-storage (package ships its own types).

fix

Ensure that 'skipLibCheck' is not true in tsconfig.json or add 'use-local-storage' to types in tsconfig.

Uncaught SyntaxError: Unexpected token u in JSON at position 0

Trying to parse an undefined value from localStorage when using JSON.parse directly, but use-local-storage handles this internally. This error occurs if you misuse the hook or have a custom parser that doesn't handle undefined.

fix

Do not call JSON.parse on the value yourself; rely on the hook's default parser or provide a custom one that checks for null/undefined.

TypeError: Cannot read properties of undefined (reading 'length')

Calling useLocalStorage without a key argument (undefined key).

fix

Always provide a valid string as the first argument (the localStorage key).

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

reactrequiredrequired as a peer dependency for the hook to work

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/nas5w/use-local-storage#readme ↗

packageuse-local-storage ↗

homepagehttps://github.com/nas5w/use-local-storage#readme ↗