Image for post

Image for post

Giovanni Benussi

Persist React’s useState to localStorage is a common requirement. You’d want to persist user’s preferences or data to have them at hand on next sessions. However, there are some bugs that are hard to track when doing this. This article will present them and explain how to solve them effectively.

Let’s suppose that we add a new settings to allow users to enable dark mode in our website. Something like this:

Image for post

Image for post

Our new dark mode setting.

Internally, we’d keep an internal state using React’s useState to store the following:

  • title: label to display in the UI
  • name: to reference in the input field and to be able to retrieve our persisted state even if we update its title.
  • enabled: specifies if the checkbox is checked or not.

To store this state we’ll use React’s useState hook for now:

Image for post

Image for post

Persist options using React’s useState.

I’ll omit the layout details and logic used to enable/disable every option since is beyond the idea of this article.

So here’s our UI and it’s associated state:

Image for post

Image for post

Our UI and its associated state when dark mode is

This is how it looks when dark mode is disabled:

Image for post

Image for post

Our UI and its associated state when dark mode is disabled

Now we have our data driven UI ready to be persisted, so we’ll do that now.

To persist our state, we’ll use the useLocalStorage hook:

Image for post

Image for post

Persist options using React’s useLocalStorage.

Notice that we need to specify options as a first parameter. This is because React’s hooks rely on call order, so there isn’t a reliable way to persist state without a name. That’s why we use options as a name to reference our state. We need to be careful to not use this name in multiple places (unless we want to reuse the same state across our app, in which case a custom hook will be a better option to keep the state’s shape in sync).

The way useLocalStorage works is as follows:

  • If there isn’t data on localStorage, set state to initial state.
  • If there is data on localStorage, set state to stored state.

Here’s a visualization of our UI and its associated state and localStorage content:

Image for post

Image for post

Now we have our data driven, persisted UI. We’ll see what issues happen when we try to add new options to it.

Let’s add a new configuration to enable data savings mode:

Image for post

Image for post

Our new data saving option.

Easy, we add just a new option to our new state:

Image for post

Image for post

Adding a data saving option to our options state.

We save our changes but we see this:

Image for post

Image for post

How our settings looks after our changes

We refresh the browser and restart the app but the UI doesn’t get updated. However, if you open our app in a new window, you’ll see the new UI:

Image for post

Image for post

How our settings looks after our changes on an incognito tab

What happened?

The issue lies on the data that we have saved on localStorage:

Image for post

Image for post

localStorage data persisted for our state.

As described before, the useLocalStorage hook will load data from localStorage if it’s present, so it loads this data as our state:

Image for post

Image for post

App state when localStorage data was present before load the page

However, on an incognito tab (or after delete localStorage data), there’s no data in localStorage so the options state will be the provided initial state:

Image for post

Image for post

App state when localStorage data wasn’t present before load the page

The easiest solution would be to just delete localStorage data and continue. However, what happens with users that already have seen the settings page on production? They’ll have stale data and thus won’t be able to see our new data saving setting.

One easy solution can be to update the name on localStorage for our state. For example, add some sort of versioning like option-v1 . When there’s a change in the initial value, you can increment the version to option-v2 , option-v3 , and so on. The drawback is that we’ll end up using unnecessary space for our users:

Image for post

Image for post

localStorage after adding a few versions

usePersistedState solves the versioning issue by keeping a unique identifier for the provided initial value:

Image for post

Image for post

usePersistedState stores a unique hash to keep track of initial value changes

When we change our initial value the initial state is automatically loaded and previous data on localStorage gets updated automatically ✨:

Image for post

Image for post

usePersistedState’s automatically updates previous data

The way it works is as follows. If there isn’t persisted data, then load state from initial state. However, if there’s data, a unique hash is calculated for the initial state and is compared against the stored one:

Image for post

Image for post

usePersistedState’s automatic hash comparison

If the hashes match, state will be loaded from localStorage. If they don’t match, it will not be considered and will be overridden by the new default state.

If you need server side support when persisting state, keep in mind that data from localStorage cannot be read from the server, so you need to delay the data loading until the component is mount on the client (running useEffect works for this). usePersistedState handles this automatically for you so you don’t need to worry about it.

If you’re worries about the performance of calculate a hash for the initial state, I did a small test and run the hash function 1,000 times and it took less than 230ms to run. That equals to 0.23ms for each run so it’s not a big deal.

Read More

ترك الرد

من فضلك ادخل تعليقك
من فضلك ادخل اسمك هنا