use-local-storage-safe

React hook for using LocalStorage safely

Installation

npm i use-local-storage-safe        # npm

yarn add use-local-storage-safe     # yarn

pnpm i use-local-storage-safe       # pnpm

Why

• Persist data to local storage using a React useState-like interface.
• Validates stored content on hook initialization to prevent collisions and handle legacy data
• Fit any hooks-compatible version of React >=16.8.0
• ESM - ECMAScript modules; CJS - CommonJS support
• Cross-Browser State Synchronization options.sync?: boolean
• SSR support (NextJS, Astro, Remix)

Usage

Basic

import { useLocalStorageSafe } from 'use-local-storage-safe'

export default function NameComponent() {
    const [userName, setUserName] = useLocalStorageSafe('name-storage-key', 'default-name')
}

Advanced

import { useLocalStorageSafe } from 'use-local-storage-safe'
// data could be validated with plain JS or any other library
import { z } from "zod";

const User = z.object({
    firstName: z.string().min(1).max(18),
    lastName: z.string().min(1).max(18),
    email: z.string().email(),
});

type User = z.infer<typeof User>

export default function UserComponent() {
    const [user, setUser] = useLocalStorageSafe<User>(
        "user-storage-key",
        {
            firstName: "example name",
            lastName: "example last name",
            email: "[email protected]",
        },
        // validate stored data on hook initialization
        { validateInit: (user) => User.safeParse(user).success }
    );

    return (
        <div>
            <p>First Name: {user.firstName}</p>
            <p>Last Name: {user.lastName}</p>
            <p>Email: {user.email}</p>

            <button
                onClick={() =>
                    setUser({ firstName: "U", lastName: "Nu", email: "[email protected]" })
                }
            >
                Set User
            </button>
        </div>
    );
}

API

function useLocalStorageSafe<T>(key: string, defaultValue?: T, options?: Options<T>): [T, Dispatch<SetStateAction<T>>];

interface Options<T> {
    stringify?: (value: unknown) => string;
    parse?: (string: string) => string;
    log?: (message: unknown) => void;
    validateInit?: (value: T) => boolean;
    sync?: boolean;
    silent?: boolean;
}

• key - The key under which the state value will be stored in the local storage.
• defaultValue - The initial value for the state. If the key does not exist in the local storage, this value will be used as the default.
• options - An object containing additional customization options for the hook.
  • options?.stringify - A function that converts the state value to a string before storing it in the local storage. JSON.stringify by default.
  • options?.parse - A function that converts the string value from the local storage back into its original form. JSON.parse by default.
  • options?.log - A function that receives a message as an argument and logs it. This can be used for debugging or logging purposes. console.log by default.
  • options?.validateInit - A function that validates stored value during hook initialization. If the validation returns false, invalid value will be removed and replaced by default if provided.
  • options?.sync - A boolean indicating whether the state should be synchronized across multiple tabs, windows and iframes. true by default.
  • options?.silent - A boolean indicating whether the hook should suppress an error occurs while accessing the local storage. true by default.