use-local-storage-state
    TypeScript icon, indicating that this package has built-in type declarations

    11.0.0 • Public • Published

    use-local-storage-state

    React hook that persist data in local storage

    Build Status Test Coverage Minified Size Minified Size

    Install

    npm install use-local-storage-state

    Why

    Few other libraries also try to abstract the usage of localStorage into a hook. Here are the reasons why you would consider this one:

    • Uses JSON.parse() and JSON.stringify() to support non string values
    • SSR support
    • 100% test coverage. No istanbul ignore
    • Handles edge cases – example
    • Subscribes to the Window storage event which tracks changes across browser tabs and iframe's
    • Aiming for high-quality with my open-source principles

    Usage

    import useLocalStorageState from 'use-local-storage-state'
    
    const [todos, setTodos] = useLocalStorageState('todos', [
        'buy milk',
        'do 50 push-ups'
    ])

    Todo list example

    You can experiment with the example here.

    import React, { useState } from 'react'
    import useLocalStorageState from 'use-local-storage-state'
    
    export default function Todos() {
        const [query, setQuery] = useState('')
        const [todos, setTodos] = useLocalStorageState('todos', ['buy milk'])
    
        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>))}
            </>
        )
    }

    Reseting to defaults

    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'
    
    const [todos, setTodos, { removeItem }] = useLocalStorageState('todos', [
        'buy milk',
        'do 50 push-ups'
    ])
    
    function onClick() {
        removeItem()
    }

    Handling edge cases with isPersistent

    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', ['buy milk'])
    
        return (
            <>
                {todos.map(todo => (<div>{todo}</div>))}
                {!isPersistent && <span>Changes aren't currently persisted.</span>}
            </>
        )
    }

    API

    useLocalStorageState(key, defaultValue?)

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

    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.

    defaultValue

    Type: any Default: undefined

    The initial value of the data. The same as useState(defaultValue) property.

    createLocalStorageStateHook(key, defaultValue?)

    If you want to have the same data in multiple components in your code use createLocalStorageStateHook() instead of useLocalStorageState(). This avoids:

    • maintenance issues with duplicate code that should always be in sync
    • conflicts with different default values
    • key parameter misspellings
    import { createLocalStorageStateHook } from 'use-local-storage-state'
    
    // Todos.tsx
    const useTodos = createLocalStorageStateHook('todos', [
        'buy milk',
        'do 50 push-ups'
    ])
    function Todos() {
        const [todos, setTodos] = useTodos()
    }
    
    // Popup.tsx
    import useTodos from './useTodos'
    function Popup() {
        const [todos, setTodos] = useTodos()
    }

    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.

    defaultValue

    Type: any Default: undefined

    The initial value of the data. The same as useState(defaultValue) property.

    Alternatives

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

    Install

    npm i use-local-storage-state

    DownloadsWeekly Downloads

    15,197

    Version

    11.0.0

    License

    MIT

    Unpacked Size

    28.6 kB

    Total Files

    22

    Last publish

    Collaborators

    • astoilkov