zustand

Zustand v4 is here

Backward compatible with v3 in JS

v4 API is completely backward compatible, so it's just nothing to update if you are JS users.

One note is v4 depends on use-sync-external-store.
There might be some bundling issues.
Please report them if you encounter such cases.

TypeScript types are rewritten

To better support types with middleware, v4 TypeScript code is rewritten.
Please find docs/typescript.md for more information.

New API for context usage

In v3, zustand/context is provided as a workaround.
v4 API exposes createStore and useStore, which are more flexible.
Please read this for usage.
If you are unsure about the usage, open a new discussion.

Counter example: codesandbox.io/s/polished-pond-4jn1e2

Deprecated APIs are removed

Some APIs are already deprecated in v3, and they are removed in v4. Please make sure to update to the latest version of v3 before migrating to v4.

What's Changed

• breaking

  vanilla: Drop deprecated store.subscribe with selector

• breaking

  middleware: Drop deprecated persist options and make removeItem required

• breaking

  core: Drop v2 hook compatibility

• breaking

  types: Drop deprecated UseStore type

• use-sync-external-store

• breaking

  middleware/devtools: Use official devtools extension types

• breaking

  middleware/devtools: Remove deprecations and warnings

• build: Separate vanilla build

• breaking

  types: Add higher kinded mutator types

• index: Export createStore from vanilla

• middleware: Separate immer middleware

• middleware/devtools: Add enabled option and show devtools warning only if enabled

• breaking

  middleware/devtools: Remove checking old string option

• Fix TS4023 and other minor changes

• types: Avoid any in react.ts

• build: Add downlevel-dts

• types: Mark more methods bivariant

• shallow: Restrict types

• persist: Add method getOptions on persist api and update documentation

• types: Minimize types by deprecating them

• build: A workaround for ESM for use-sync-external-store

• types: Use TS interfaces only for public api

• shallow: Types with useStore

• shallow: Types with useStore again

This fixes an issue in persist for some use cases.

What's Changed

• middleware/persist: Merge storage value with the latest store state

This fixes a type issue with zustand/context in v3.7.0.

What's Changed

• context: Revert removing overloads in UseContextStore

• deprecated

  middleware/devtools: Deprecate serialize.options

This release is to prepare for v4 release, which will include some breaking changes. Especially typing store with middleware will be changed. This release gives partial migration path (see tests/middlewareTypes.test.tsx for examples), so it's highly recommended to try this version before v4 comes and report issues.

It also fixes some small typing issues and improves UMD/SystemJS bundling. Oh, and last but not least, vite users don't need to set NODE_ENV anymore.

What's Changed

• devtools: Don't show jsdoc deprecation warning when no options are passed

• middleware: Match vanilla StateCreator type in subscribeWithSelector

• build: Use __DEV__ to control development mode

• Migrations regarding higher kinded mutators for v4

This adds UMD and SystemJS builds for CDN.

What's Changed

• build: Generate umd and system files

This fixes some issues in devtools middleware.

What's Changed

• middleware/devtools: Minor fixes for pause recording feature

• middleware/devtools: Revert extension connector with try-catch to fix RN usage

• deprecated

  middleware/devtools: Deprecate passing name directly instead of an object

There was a regression in devtools middleware in v3.6.6, which is fixed.

What's Changed

• middleware: Devtools work in non-browser

This fixes and improves devtools middleware. The basic usage shouldn't be changed. If you have questions on usage, please open a new discussion.

What's Changed

• Rewrite devtools

This version further improves to fix some typing issues introduced in v3.6.0 and fixes persist api introduced in v3.6.3.

What's Changed

• types: Fix core types to better handle middleware types

• middleware: Add onFinishHydration to persist api

This improves devtools middleware and typing of other middlewares. Please feel free to update and report any issues.

What's Changed

• middleware: Devtools to patch api.setState with namedSet and fix middleware types

The new persist middleware exposes persist api in store. This is thanks to the new customizable store api types introduced in v3.6.

What's Changed

• core: useDebugValue in useStore

• middleware: Add persist api

v3.6.0 introduced middleware types trying to infer store types as much as possible. However, it doesn't work well for several cases, and users need to type manually which was actually hard. In this version, middleware types are simplified and let users to explicitly type when needed more easily. Many examples are in tests/middlewareTypes.test.tsx. If you find issues or need some more typing examples, please report them.

What's Changed

• middleware: Simplify middleware types and allow explicit typing

Summary

This fixes some type issues introduced in v3.6.0. devtools is improved to accept updating state from DevTools Ext.

What's Changed

• context: Custom store type for createContext

• middleware: Devtools dispatch support

• middleware: Types and devtools

Summary

This version mainly comes with type improvement for middleware. It's tricky implementation-wise. Please report issues and let's look for solutions or workarounds.
It has renamed and deprecated types: UseStore 👉 UseBoundStore
A new subscribeWithSelector middleware is added, deprecating the equivalent feature in core.

Migrating to subscribeWithSelector middleware

Previously, you could do this:

const useStore = create(...)
useStore.subscribe(callback, selector, equalityFn)

which is deprecated and replaced with:

const useStore = create(subscribeWithSelector(...))
useStore.subscribe(selector, callback, { equalityFn }) // selector is not optional

What's Changed

• types: Better middleware support

• types: Rename from UseStore to UseBoundStore

• middleware: subscribeWithSelector middleware

Summary

Fixed a regression in devtools that was introduced in v3.5.11.

What's Changed

• middleware: Export PersistOptions type definitions

• middleware: Jump state support in devtools

The persist middleware has a new option partialize which works for nested properties, deprecating blacklist and whitelist options.

• persist: Add partialize option

v3.5.11 accidentally requires newer node.js versions. v3.5.12 fixes it by reverting exports format.

• package: Avoid subpath pattern in exports

⚠️ Minimum Node.js requirements (for server-side usage like Next.js): v14.13.0, v12.20.0

This improved devtools middleware. There can still be room for improvement. Free free to open issues and feature requests, and possibly contribute to them.

• Remove useless internal info in devtools

Our fixes for ESM in v3.5.8 and v3.5.9 were somewhat good and somewhat bad. Now, this should be the better one based on our experience and reported issues. If you still have some issues, please file them.

• Allow optional REDUX DEVTOOLS "options" object

• Rollback to initial exports structures with duplicated .js and .mjs files for additional support of bundlers

We've been struggling with providing package that works for various bundlers and node.
v3.5.8 was expected to solve the issue with node, but it turned out having an issue with webpack 5.
We basically gave up supporting old bundlers. v3.5.9 comes with simplified builds with latest standard.

Note for old bundlers like webpack 4: Unlike previous versions, the bundler will pick cjs build by default. If you need module build, it should be explicit. Free free to open an issue for questions and discussions.

• Package all files into a single dist folder

This improves ESM build.

• build: Improved ESM support for most used bundlers with fallbacks for older bundlers

This includes a fix for zustand/context for TypeScript.

• context: Export UseContextStore interface

This fixed zustand/context types and added "import" export entries for modern bundlers.

• Revert Provider initialStore types

• Improve createContext's useStore types

• Package.json exports to have import

This supports IE11 again. (v3.5.3 and v3.5.4 have an issue.)
It also has various fixes and improvements in the persist middleware.

• persist: onRehydrateStorage argument not containing the final state

• persist: Add a merge function option

• Do not use generator to support IE11

• persist: Incorrect deserialize return type

• persist: Not hydrating when the stored item doesn't contain a version

v3.5.3 has an issue in CJS build. Please use this instead.

• Cjs build, no regenerator

(v3.5.3 includes #419, which causes a build issue in CJS. Please use v3.5.4)

This includes some type improvements in zustand/middleware and improvements/changes in zustand/context.

• Export NamedSet type for combining with immer

• middleware/persist: Argument of onRehydrateStorage for missing migrate function

• Make type NamedSet compatible with type SetState

• context: Stable storeApi

• Fix/context create store

This has various small but non-trivial improvements.

• Allow optional selector in zustand/vanilla #384

• Fix a return value type of combine #395

• Expose StateStorage type and update persist midlware documentation #412

• (types): improve types for setState #397

• Migrating Async/Await to Promise #403

This includes some fixes in zustand/context.

• Add useStoreApi context hook #380

• Removed "initialState" parameter from createContext() #382

This modifies State base type. It's stricter than before and can be a breaking change for TS users. This also adds a new bundle zustand/context which provides a helper function for the usage with React context.

• #376

• #375

This includes two small updates.

• persist middleware: Incorrect deserialize type #359

• Add import of store state json to devtools middleware #373

v3.4.0 has a serious issue in the CJS build. This it to fix it.

• #352

(IMPORTANT: It turns out that this version has a serious issue in CJS build. Please use v3.4.1 instead.)

This release is mainly to change build tooling and package file structure. It now uses esbuild to build esm bundles. The esm bundles are in esm folder, and default cjs bundles are in the root folder.

• breaking

  Index.cjs.js is renamed to index.js (explicit cjs usage is no longer documented in readme)

• breaking

  Index.iife.js is removed (never documented and not configured properly)

Changes:

• #350

• #348

• #343

This improves types for setState in TypeScript.

• #320

This improves persist middleware.

• #284

• #292

This patch release fixes an edge case with useLayoutEffect

• #280

[BREAKING CHANGE] Improved persist middleware

See

• breaking

  storage options is replaced with getStorage

• breaking

  New blacklist / whitelist options

• breaking

  New onRehydrateStorage option

• breaking

  New version option (data format is changed)

Improved types for TypeScript

• #257

• #266

This release improves scoped subscription api (subscription with selector).

• #241

[BREAKING CHANGE]
This includes a breaking change in undocumented api and behavior.

Pre-v3.2:

const store = create(...)

store.subscribe((foo, error) => {
  ...
}, state => state.foo)

// errors in the selector are caught and passed as the second argument of the listener.

v3.2:

const store = create(...)

store.subscribe((foo, prevFoo) => {
  ...
}, state => state.foo)

// the second argument of the listener is previous value and errors in the selector are not caught.

This patch release adds a new persist middleware.

• #229

This patch release adds a small fix in devtools middleware.

• #196

This patch release adds an improvement in devtools middleware.

• #188

Bug fixes

• #179

Doc fixes

• #176

• #177

• #181

This release is mainly for TypeScript users.

The base State type is stricter.

In v3.0.3:

In v3.1.0:

To fix it:

See also:

• #183

New combine middleware

This will combine two parts of state into one. The first part is primitive state, and the second part is actions that depend on set.

The resulting type is inferred from the state creator.

This fixes a bug in devtools middleware.

• #172

This fixes some issues in middleware.

BREAKING CHANGE in devtools: set now requires replace introduced in v3 api. ref: #159

• #164

• #167

• #169

What's new

First of all, this release is 100% backward compatible, it will not break your code! The only breaking change (the create functions return value) still can work in the old way, but throws a small deprecation warning.

Our main focus has been:

• Stability and fixing bugs

• Making it suitable for concurrent mode

• Supporting React-fast-refresh

• Making it more versatile so that it can be used without React

We will soon publish an experimental V4 that utilizes react-experimentals useMutableSource in concurrent mode. The groundwork for this has been laid in this major.

Simpler API !(img.shields.io/badge/-deprecations-red)

import create from 'zustand'

const useStore = create(set => ({
  bears: 0,
  increasePopulation: () => set(state => ({ count: state.bears + 1 })),
  resetPopulation: () => set({ bears: 0 })
}))

function BearCounter() {
  const bears = useStore(state => state.bears)
  return <h1>{bears} around here ...</h1>
}

function Controls() {
  const increasePopulation = useStore(state => state.increasePopulation)
  return <button onClick={increasePopulation}>one up</button>
}

Utility functions are on the hooks prototype !(img.shields.io/badge/-deprecations-red)

Sometimes you need to access the state in a non-reactive way, or act upon the store. For these cases the resulting hook has utility functions attached to its prototype.

const useStore = create(() => ({ paw: true, snout: true, fur: true }))

// Getting non-reactive fresh state
const paw = useStore.getState().paw
// Listening to all changes, fires on every change
const unsub1 = useStore.subscribe(console.log)
// Listening to selected changes, in this case when "paw" changes
const unsub2 = useStore.subscribe(console.log, state => state.paw)
// Updating state, will trigger listeners
useStore.setState({ paw: false })
// Unsubscribe listeners
unsub1()
unsub2()
// Destroying the store (removing all listeners)
useStore.destroy()

// You can of course use the hook as you always would
function Component() {
  const paw = useStore(state => state.paw)

Using zustand without React

Zustands core can be imported and used without the React dependency. The only difference is that the create function does not return a hook, but the api utilities.

import create from 'zustand/vanilla'

const store = create(() => ({ ... }))
const { getState, setState, subscribe, destroy } = store

You can even consume an existing vanilla store with React:

import create from 'zustand'
import vanillaStore from './vanillaStore'

const useStore = create(vanillaStore)

Overwriting state

The set function has a second argument, false by default. Instead of merging, it will replace the state model. Be careful not to wipe out parts you rely on, like actions.

import omit from "lodash-es/omit"

const useStore = create(set => ({
  salmon: 1,
  tuna: 2,
  deleteEverything: () => set({ }), true), // clears the entire store, actions included
  deleteTuna: () => set(state => omit(state, ['tuna']), true)
}))