README.md

Use State Persist

A simple React Hook to persist useState in local storage.

Works on the Web and React Native.

Easily implement

• Offline state
• Stale while revalidate flow
• Global state

npm install use-state-persist
# or
yarn add use-state-persist

For React Native make sure you do the following on app start up:

import { syncStorage } from 'use-state-persist';

// Initialize async storage
await syncStorage.init();

How to persists useState

Same behavior and API as useState so you can use it by easily replacing the useState hook for the calls which you want to persist offline.

import { useStatePersist as useState } from 'use-state-persist';

const Component = () => {
  // Before
  //const [counter, setCounter] = useState(0);
  const [counter, setCounter] = useState('@counter', 0);

  return <CounterDisplay value={counter} />;
};

Stale While Revalidate

import { useStatePersist as useState } from 'use-state-persist';

const Component = () => {
  // Loads stale state
  const [data, setData] = useState('@data');

  const fetchData = async () => {
    // Fetches new state
    const data = await fetch('/endpoint');
    setData(data);
  };

  useEffect(() => {
    fetchData();
  }, []);

  return <DataDisplay value={data} />;
};

Global State

Simple event system allows all the storage writes to be dispatched to all hooks . That means that all useStatePersist() can be used as a global state by sharing the same key useStatePersist('@globalKey')

To avoid that just make sure that the key being passed to the hook is unique useStatePersist('@uniqueKey')

const CounterButton = () => {
  const [counter, setCounter] = useState('@counter');

  return <Button onClick={() => setCounter(counter => counter++)} />;
};

State will be updated across multiple components

const ShowCounter = () => {
  const [counter, setCounter] = useState('@counter', 0);

  return <CounterDisplay value={counter} />;
};

Cache Invalidation

There are some cases where you might want to clear all the local storage cache for the hook, pending a certain change in state in the app.

This will clear all the local storage items use by the useStatePersist hook when the key changes.

Use Cases

• User/App State changes
• User Log out
• Environment variable changes

import { invalidateCache } from 'use-state-persist';

invalidateCache('CACHE_KEY');

// You can also send a promise which will compare the result
invalidateCache(async () => 'CACHE_KEY');

React Native

Init prepares the SyncStorage to work synchronously, by getting all values for all keys stored on AsyncStorage. You can use the init method on the web without any side effects to keep code consistency.

import { syncStorage } from 'use-state-persist';

await syncStorage.init();