Persisting State on React Apps

Published Originally on Medium

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.

Our Example

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

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:

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:

This is how it looks when dark mode is disabled:

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

Persisting State

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

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:

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

Stale State

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

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

We save our changes but we see this:

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

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

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

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:

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.

Versioning

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:

Automatic Updates

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

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

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:

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.

Server Side Support

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.

Performance

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.

Conclusion

In this article I introduce you about common issues when persisting state to localStorage. We saw a simple way to automatically adapt to changes and avoid hard to find bugs at the same time.
If you haven't done it yet, I encourage you to use usePersistedState for this purpose. I build it with ❤️ and hard work so you don't have to.
You can find me on Twitter if you have any questions.