Cover image for Persisting State on React Apps

Persisting State on React Apps

giovannibenussi profile image Giovanni ・5 min read

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:

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:

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:

Our UI and its associated state when dark mode is enabled

This is how it looks when dark mode is disabled:

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.

Persisting State

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

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:

Alt Text

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:

Our new data saving option.

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

Adding a data saving option to our options state.

We save our changes but we see this:

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 incognito window, you'll see the new UI:

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:

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:

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:

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:

localStorage after adding a few versions

Automatic Updates

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

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 ✨:

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:

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.

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.


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.


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.


Editor guide