In this article, we’ll explore how Zustand enables state replacement with the setState function, focusing on an interesting feature: overriding the state without merging. We'll explain how to use it with a simple test case.

Understanding State Merging vs State Overriding

Before looking at the code, it’s important to understand the difference between merging and overriding state.

Merging State: By default, when you update state in Zustand (or React), it merges the new state with the existing state. Only the updated fields are changed, while the rest of the state remains intact.
Overriding State: In contrast, overriding the state replaces the entire state with a new object, discarding any fields that were present in the previous state but are not part of the new state.

When to Override State

There are situations where replacing the entire state is necessary, for instance:

Resetting state after a form submission.
Replacing state entirely when loading a different dataset.

Test Case for Overriding Zustand State

Here’s a simple test case from Zustand’s codebase that demonstrates how to override the state using the setState function:


it('can set the store without merging', () => {
  const { setState, getState } = create<{ a: number } | { b: number }>(
    (_set) => ({
      a: 1,
    }),
  )
 
  // Should override the state instead of merging.
  setState({ b: 2 }, true)
  expect(getState()).toEqual({ b: 2 })
})

Breaking Down the Test

1. Creating the Store First, a Zustand store is created with an initial state:


const { setState, getState } = create<{ a: number } | { b: number }>(
    (_set) => ({
      a: 1,
    }),
  )

The initial state is an object with a single property a set to 1. The create function returns two essential methods:

setState: This method is used to update the store’s state.
getState: This method retrieves the current state of the store.

2. Overriding the State The key operation here is to replace the current state, { a: 1 }, with a completely new state:


setState({ b: 2 }, true)

By passing the true flag as the second argument, Zustand knows that it should override the state, rather than merge the new object { b: 2 } with the existing one. This completely replaces the previous state, so { a: 1 } is removed, and the new state becomes { b: 2 }.

3. Validating the State Replacement Finally, the test ensures that the state has been fully replaced:


expect(getState()).toEqual({ b: 2 })

The expectation is that after calling setState({ b: 2 }, true), the store’s state will only contain { b: 2 } and no longer contain { a: 1 }.

How Zustand Overrides State

The below image is from Zustand source code that sets state.

As you can see, if replace flag exists, nextState become the new state.


(replace ?? (typeof nextState !== 'object' || nextState === null))

This is a clever way, if replace is false, which it is by default, (typeof nextState !== ‘object’ || nextState === null)) condition is checked.

Conclusion

Zustand offers a straightforward way to manage state in React, and the ability to override the state completely using setState with the override flag provides additional flexibility. Whether you want to reset a form, load new data, or clear out old values, this feature allows you to fully control how state is managed and updated in your application.

About me:

Hey, my name is Ramu Narasinga. I study large open-source projects and create content about their codebase architecture and best practices, sharing it through articles, videos.

I am open to work on interesting projects. Send me an email at ramu.narasinga@gmail.com

My Github — https://github.com/ramu-narasinga

My website — https://ramunarasinga.com

My Youtube channel — https://www.youtube.com/@thinkthroo

Learning platform — https://thinkthroo.com

Codebase Architecture — https://app.thinkthroo.com/architecture

Best practices — https://app.thinkthroo.com/best-practices

Production-grade projects — https://app.thinkthroo.com/production-grade-projects

How to override your Zustand state.