use-local-storage-state

What is use-local-storage-state?

The use-local-storage-state package is a React hook that simplifies the use of localStorage in React applications. It provides a way to persist state in localStorage, making it easy to manage and synchronize state with localStorage automatically.

What are use-local-storage-state's main functionalities?

Persisting State

This feature allows you to persist a piece of state in localStorage. The hook returns a stateful value and a function to update it, similar to useState, but the value is also stored in localStorage under the specified key.

import useLocalStorageState from 'use-local-storage-state';

function App() {
  const [name, setName] = useLocalStorageState('name', '');

  return (
    <div>
      <input
        type="text"
        value={name}
        onChange={(e) => setName(e.target.value)}
      />
      <p>Hello, {name}!</p>
    </div>
  );
}

Default Value

You can provide a default value that will be used if there is no existing value in localStorage. This makes it easy to initialize state with a default value.

import useLocalStorageState from 'use-local-storage-state';

function App() {
  const [count, setCount] = useLocalStorageState('count', 0);

  return (
    <div>
      <button onClick={() => setCount(count + 1)}>Increment</button>
      <p>Count: {count}</p>
    </div>
  );
}

JSON Support

The hook supports storing complex data structures like objects and arrays in localStorage by automatically handling JSON serialization and deserialization.

import useLocalStorageState from 'use-local-storage-state';

function App() {
  const [user, setUser] = useLocalStorageState('user', { name: '', age: 0 });

  return (
    <div>
      <input
        type="text"
        value={user.name}
        onChange={(e) => setUser({ ...user, name: e.target.value })}
      />
      <input
        type="number"
        value={user.age}
        onChange={(e) => setUser({ ...user, age: Number(e.target.value) })}
      />
      <p>{user.name} is {user.age} years old.</p>
    </div>
  );
}

Other packages similar to use-local-storage-state

react-use

react-use is a collection of essential React Hooks, including a useLocalStorage hook. It provides similar functionality to use-local-storage-state but as part of a larger suite of hooks. It may be more suitable if you need a variety of hooks in addition to localStorage management.

usehooks-ts

usehooks-ts is a collection of React hooks written in TypeScript, including a useLocalStorage hook. It offers similar functionality to use-local-storage-state with TypeScript support, making it a good choice for TypeScript projects.

use-persisted-state

use-persisted-state is another React hook for persisting state in localStorage. It provides a similar API to use-local-storage-state but is more lightweight, focusing solely on state persistence without additional features.

README

use-local-storage-state

React hook that persist data in localStorage

Install

npm install use-local-storage-state@17

Why

• Actively maintained for the past 2 years — see contributions page.
• SSR support with handling of hydration mismatches.
• Handles the Window storage event and updates changes across browser tabs, windows, and iframe's.
• In-memory fallback when localStorage throws an error and can't store the data. Provides a isPersistent API to let you notify the user their data isn't currently being stored.
• Aiming for high-quality with my open-source principles.

Usage

import useLocalStorageState from 'use-local-storage-state'

export default function Todos() {
    const [todos, setTodos] = useLocalStorageState('todos', {
        ssr: true,
        defaultValue: ['buy avocado', 'do 50 push-ups']
    })
}

Todo list example + CodeSandbox link

You can experiment with the example here.

import React, { useState } from 'react'
import useLocalStorageState from 'use-local-storage-state'

export default function Todos() {
    const [todos, setTodos] = useLocalStorageState('todos', {
        ssr: true,
        defaultValue: ['buy avocado']
    })
    const [query, setQuery] = useState('')

    function onClick() {
        setQuery('')
        setTodos([...todos, query])
    }

    return (
        <>
            <input value={query} onChange={e => setQuery(e.target.value)} />
            <button onClick={onClick}>Create</button>
            {todos.map(todo => (
                <div>{todo}</div>
            ))}
        </>
    )
}

SSR support

SSR supports includes handling of hydration mismatches. This prevents the following error: Warning: Expected server HTML to contain a matching .... This is the only library I'm aware of that handles this case. For more, see discussion here.

import useLocalStorageState from 'use-local-storage-state'

export default function Todos() {
    const [todos, setTodos] = useLocalStorageState('todos', {
        ssr: true,
        defaultValue: ['buy avocado', 'do 50 push-ups']
    })
}

Notify the user when localStorage isn't saving the data using the `isPersistent` property

There are a few cases when localStorage isn't available. The isPersistent property tells you if the data is persisted in localStorage or in-memory. Useful when you want to notify the user that their data won't be persisted.

import React, { useState } from 'react'
import useLocalStorageState from 'use-local-storage-state'

export default function Todos() {
    const [todos, setTodos, { isPersistent }] = useLocalStorageState('todos', {
        defaultValue: ['buy avocado']
    })

    return (
        <>
            {todos.map(todo => (<div>{todo}</div>))}
            {!isPersistent && <span>Changes aren't currently persisted.</span>}
        </>
    )
}

Removing the data from localStorage and resetting to the default

The removeItem() method will reset the value to its default and will remove the key from the localStorage. It returns to the same state as when the hook was initially created.

import useLocalStorageState from 'use-local-storage-state'

export default function Todos() {
    const [todos, setTodos, { removeItem }] = useLocalStorageState('todos', {
        defaultValue: ['buy avocado']
    })

    function onClick() {
        removeItem()
    }
}

API

useLocalStorageState(key, options?)

Returns [value, setValue, { removeItem, isPersistent }] when called. The first two values are the same as useState(). The third value contains two extra properties:

• removeItem() — calls localStorage.removeItem(key) and resets the hook to it's default state
• isPersistent — boolean property that returns false if localStorage is throwing an error and the data is stored only in-memory

key

Type: string

The key used when calling localStorage.setItem(key) and localStorage.getItem(key).

⚠️ Be careful with name conflicts as it is possible to access a property which is already in localStorage that was created from another place in the codebase or in an old version of the application.

options.defaultValue

Type: any

Default: undefined

The default value. You can think of it as the same as useState(defaultValue).

options.ssr

Type: boolean

Default: false

Enables SSR support and handles hydration mismatches. Not enabling this can cause the following error: Warning: Expected server HTML to contain a matching .... This is the only library I'm aware of that handles this case. For more, see discussion here.

options.storageSync

Type: boolean

Default: true

Setting to false doesn't subscribe to the Window storage event. If you set to false, updates won't be synchronized across tabs, windows and iframes.

Alternatives

These are the best alternatives to my repo I have found so far:

• donavon/use-persisted-state
• imbhargav5/rooks
• dance2die/react-use-localstorage