zustand

library5.0.12jsnpmunverified

Zustand is a lightweight, fast, and scalable state-management solution for React, built on simplified flux principles. It offers a comfortable API based on hooks, designed to be unopinionated and address common React pitfalls like the zombie child problem. The current stable version is 5.0.12, with active development and frequent patch releases.

web-framework testing

npm install zustand

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ZUSTAND

zustand

web-frameworkjavascriptv5.0.12

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

create

✓ import { create } from 'zustand'

✗ const { create } = require('zustand')

Zustand is primarily designed for ESM usage with React hooks. While CommonJS might work with some bundlers, ESM is the recommended and idiomatic approach.

This quickstart defines a simple Zustand store, `useBearStore`, with initial state and actions. It then demonstrates how to consume and update this state from two separate React components without needing a Provider.

import { create } from 'zustand'; const useBearStore = create((set) => ({ bears: 0, increasePopulation: () => set((state) => ({ bears: state.bears + 1 })), removeAllBears: () => set({ bears: 0 }), })); function BearCounter() { const bears = useBearStore((state) => state.bears); return <h1>{bears} around here ...</h1>; } function Controls() { const increasePopulation = useBearStore((state) => state.increasePopulation); return <button onClick={increasePopulation}>one up</button>; }

Debug

Known issues

gotchaState updates must be immutable. Directly modifying state objects will not trigger re-renders or correctly persist changes.

fix

Always return a new state object from `set` callbacks (e.g., `set((state) => ({ ...state, property: newValue }))`) or provide a new object when calling `set`.

affects: >=5.0.0

gotchaSelecting the entire store state (e.g., `useBearStore()`) will cause your component to re-render on *any* state change within the store, which can lead to performance issues.

fix

Select only the specific state slices your component needs (e.g., `useBearStore((state) => state.bears)`). For multiple non-primitive slices, consider `shallow` from `zustand/shallow` or a custom equality function.

affects: >=5.0.0

gotchaSelectors use strict-equality (`old === new`) for comparison by default. If your selector returns a new object or array on every render, it will cause unnecessary re-renders even if the underlying data is shallowly identical.

fix

For non-primitive return values from selectors (e.g., `useBearStore((state) => ({ count: state.bears, name: state.name }))`), use `shallow` from `zustand/shallow` as a second argument to `useBearStore` (e.g., `useBearStore(selector, shallow)`).

affects: >=5.0.0

gotchaWhen using the `persist` middleware, directly manipulating the underlying storage (like `localStorage`) outside of Zustand's API can lead to state inconsistencies or race conditions, especially during concurrent rehydration.

fix

Manage all persistent state exclusively through Zustand's `persist` middleware and `set` function, avoiding direct interaction with the storage API.

affects: >=5.0.0

Errors

Common errors & fixes

TypeError: Cannot destructure property 'create' of 'zustand' as it is undefined.

Attempting to use CommonJS `require` syntax for `zustand` which might primarily target ESM, or an incorrect module import path.

fix

Ensure you are using `import { create } from 'zustand'` and your build system is configured for ESM.

Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

Calling `useBearStore` or any other Zustand store hook outside of a React function component or another custom React Hook.

fix

Ensure all Zustand store hooks are invoked exclusively within the top level of React function components or custom hooks.

TypeError: Cannot read properties of undefined (reading 'propertyName')

A `set` callback returned `void` or `undefined` instead of a state object, causing the store state to become invalid or partial updates to fail.

fix

Always ensure `set` callbacks return a complete (or new partial) state object. For example, `set((state) => ({ ...state, propertyName: newValue }))`.

Upgrade

Version history

5.0.12latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

70 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/pmndrs/zustand ↗

packagehttps://www.npmjs.com/package/zustand ↗

homepagehttps://zustand-demo.pmnd.rs ↗