{"id":15072,"library":"zustand","title":"Zustand State Management","description":"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.","status":"active","version":"5.0.12","language":"javascript","source_language":"en","source_url":"https://github.com/pmndrs/zustand","tags":["javascript","react","state","manager","management","redux","store","typescript"],"install":[{"cmd":"npm install zustand","lang":"bash","label":"npm"},{"cmd":"yarn add zustand","lang":"bash","label":"yarn"},{"cmd":"pnpm add zustand","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Zustand is primarily designed for ESM usage with React hooks. While CommonJS might work with some bundlers, ESM is the recommended and idiomatic approach.","wrong":"const { create } = require('zustand')","symbol":"create","correct":"import { create } from 'zustand'"}],"quickstart":{"code":"import { create } from 'zustand';\n\nconst useBearStore = create((set) => ({\n  bears: 0,\n  increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),\n  removeAllBears: () => set({ bears: 0 }),\n}));\n\nfunction BearCounter() {\n  const bears = useBearStore((state) => state.bears);\n  return <h1>{bears} around here ...</h1>;\n}\n\nfunction Controls() {\n  const increasePopulation = useBearStore((state) => state.increasePopulation);\n  return <button onClick={increasePopulation}>one up</button>;\n}","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"State updates must be immutable. Directly modifying state objects will not trigger re-renders or correctly persist changes.","severity":"gotcha","affected_versions":">=5.0.0"},{"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.","message":"Selecting 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.","severity":"gotcha","affected_versions":">=5.0.0"},{"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)`).","message":"Selectors 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.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Manage all persistent state exclusively through Zustand's `persist` middleware and `set` function, avoiding direct interaction with the storage API.","message":"When 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.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import { create } from 'zustand'` and your build system is configured for ESM.","cause":"Attempting to use CommonJS `require` syntax for `zustand` which might primarily target ESM, or an incorrect module import path.","error":"TypeError: Cannot destructure property 'create' of 'zustand' as it is undefined."},{"fix":"Ensure all Zustand store hooks are invoked exclusively within the top level of React function components or custom hooks.","cause":"Calling `useBearStore` or any other Zustand store hook outside of a React function component or another custom React Hook.","error":"Error: Invalid hook call. Hooks can only be called inside of the body of a function component."},{"fix":"Always ensure `set` callbacks return a complete (or new partial) state object. For example, `set((state) => ({ ...state, propertyName: newValue }))`.","cause":"A `set` callback returned `void` or `undefined` instead of a state object, causing the store state to become invalid or partial updates to fail.","error":"TypeError: Cannot read properties of undefined (reading 'propertyName')"}],"ecosystem":"npm"}