use-persisted-state

The use-persisted-state library is not a hook itself, but a factory function. You call createPersistedState with a storage key and an optional storage provider (which defaults to localStorage). This factory returns a custom React hook that functions as a direct replacement for useState.

Key features include:

• Persistence: Automatically saves state to localStorage.
• Cross-tab Syncing: Synchronizes state changes across different browser tabs or windows.
• Shared State: Multiple hooks using the same key on the same page will share the same state.

import createPersistedState from 'use-persisted-state';
const useCounterState = createPersistedState('count');

// useCounterState can now be used like useState
const [count, setCount] = useCounterState(initialCount);

To use use-persisted-state in your project, install it using npm:

$ npm i use-persisted-state

To implement persistent state, import createPersistedState from the library, initialize it with a unique key, and then use the returned hook inside your component. This hook follows the same signature as useState (returning a value and a setter function).

import createPersistedState from 'use-persisted-state';

// Initialize the factory with a unique key
const useCounterState = createPersistedState('count');

const useCounter = initialCount => {
  // Use the returned hook just like useState
  const [count, setCount] = useCounterState(initialCount);

  return {
    count,
    increment: () => setCount(currentCount => currentCount + 1),
    decrement: () => setCount(currentCount => currentCount - 1),
  };
};

export default useCounter;

The createPersistedState function is the primary entrypoint for the library. It creates a factory function that, when called with an initial state, returns a React hook (usePersistedState) that automatically synchronizes state with a storage provider.

Parameters:

• key (string): The unique key used to identify the data in the storage provider.
• provider (Storage | null): An optional storage object (e.g., localStorage). If not provided, the library attempts to automatically detect a global localStorage instance. If no provider is found, it falls back to the standard React useState hook (meaning state will not be persisted).

Returns:

• A function that accepts initialState and returns the usePersistedState hook.