fsmaia / use-local-storage-state

React hook that persist data in local storage

use-local-storage-state

React hook that persist data in local storage

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. Supports server-side rendering.
• Well tested. 100% coverage.
• Handles edge cases. Example
• Subscribes to the Window storage event which tracks changes across browser tabs and iframe's.

Usage

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

const [todos, setTodos] = useLocalStorageState('todos', [
    'buy milk',
    'do 50 push-ups'
])

Todo list

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() {
        setTodos([...todos, query])
    }

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

Using the same hook in multiple places

// store.ts
import { createLocalStorageStateHook } from 'use-local-storage-state'
export const useTodos = createLocalStorageStateHook('todos', [
    'buy milk',
    'do 50 push-ups'
])

// Todos.ts
import useTodos from '../store'
function Todos() {
    const [todos, setTodos] = useTodos()
}

// Popup.ts
import useTodos from '../store'
function Popup() {
    const [todos, setTodos] = useTodos()
}

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 local storage 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, isPersistent]. The first two are the same as useState(). The third(isPersistent) determines if the data is persisted in localStorage or in-memory – example.

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?)

Returns a hook to be used in multiple places. Example

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.