Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

use-local-storage-state

Package Overview
Dependencies
Maintainers
1
Versions
83
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

use-local-storage-state

React hook that persist data in localStorage

  • 19.5.0
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
117K
increased by6.33%
Maintainers
1
Weekly downloads
 
Created
Source

use-local-storage-state

React hook that persist data in localStorage

Downloads Gzipped Size Build Status

Install

React 18 and above:

npm install use-local-storage-state

⚠️ React 17 and below. For docs, go to the react-17 branch.

npm install use-local-storage-state@17

Why

  • Actively maintained for the past 4 years — see contributors page.
  • Production ready.
  • 689 B (brotlied).
  • SSR support.
  • Works with React 18 concurrent rendering and React 19.
  • Handles the Window storage event and updates changes across browser tabs, windows, and iframe's. Disable with storageSync: false.
  • 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', {
        defaultValue: ['buy avocado', 'do 50 push-ups']
    })
}
Todo list example

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

export default function Todos() {
    const [todos, setTodos] = useLocalStorageState('todos', {
        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>
            ))}
        </>
    )
}

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()
    }
}
Why my component renders twice?

If you are hydrating your component (for example, if you are using Next.js), your component might re-render twice. This is behavior specific to React and not to this library. It's caused by the useSyncExternalStore() hook. There is no workaround. This has been discussed in the issues: https://github.com/astoilkov/use-local-storage-state/issues/56.

If you want to know if you are currently rendering the server value you can use this helper function:

function useIsServerRender() {
  return useSyncExternalStore(() => {
    return () => {}
  }, () => false, () => true)
}

API

useLocalStorageState(key: string, options?: LocalStorageOptions)

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
  • isPersistentboolean 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.defaultServerValue

Type: any

Default: undefined

The default value while server-rendering and hydrating. If not set, it will use defaultValue option instead. Set only if you want it to be different than the client value.

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.

options.serializer

Type: { stringify, parse }

Default: JSON

JSON does not serialize Date, Regex, or BigInt data. You can pass in superjson or other JSON-compatible serialization library for more advanced serialization.

Keywords

FAQs

Package last updated on 13 Nov 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc