Skip to content
React hook that persists and syncs state with local storage
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


React hook that persists state with the localStorage API. It also automatically syncs state between tabs/windows.

Getting started

npm i @illinois/react-use-local-storage

This hook functions similarly to useState, with the exception of the the caveats listed below. If your state is easily encodable in JSON and you don't use lazy initialization or functional updates, it should be easy to migrate from useState. You'll need to provide a key for getting/setting the item in local storage.

import useLocalStorage from '@illinois/react-use-local-storage'

const MyComponent = () => {
  const [count, setCount] = useLocalStorage('value-key', 0)
  return (
      <div>Count: {count}</div>
      <button onClick={() => setCount(count + 1)}>Increase</button>
      <button onClick={() => setCount(0)}>Reset</button>

Trying it out

git clone react-use-local-storage
cd react-use-local-storage
npm install
npm run storybook

This will launch a simple demo with a counter that can be incremented and reset. Try opening the demo in two tabs at once and watch how changes are automatically synced between them!


  • State is serialized with JSON.stringify and deserialized with JSON.parse. This is done because the localStorage API doesn't support storing anything but strings at present. As such, you should pay special attention to objects that might not handle being round-tripped through JSON, e.g. a Date object.

  • Unlike useState, lazy initialization is not currently supported. A PR adding support would be welcome!

  • Unlike useState, functional updates are not currently supported. A PR adding support would be welcome!

Prior art

You can’t perform that action at this time.