0
# Zustand
1

2
Zustand is a small, fast and scalable bearbones state-management solution using simplified flux principles. It has a comfy API based on hooks that isn't boilerplatey or opinionated, and eliminates common React state management pitfalls including zombie child problems, React concurrency issues, and context loss between mixed renderers.
3

4
## Package Information
5

6
- **Package Name**: zustand
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install zustand`
10

11
## Core Imports
12

13
```typescript
14
import { create } from "zustand";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { create } = require("zustand");
21
```
22

23
For vanilla (non-React) usage:
24

25
```typescript
26
import { createStore } from "zustand/vanilla";
27
```
28

29
For middleware:
30

31
```typescript
32
import { devtools, persist, subscribeWithSelector } from "zustand/middleware";
33
import { redux, combine } from "zustand/middleware";
34
import { immer } from "zustand/middleware/immer";
35
```
36

37
For utilities:
38

39
```typescript
40
import { shallow } from "zustand/shallow";
41
import { useShallow } from "zustand/react/shallow";
42
```
43

44
For traditional API with equality functions:
45

46
```typescript
47
import { createWithEqualityFn, useStoreWithEqualityFn } from "zustand/traditional";
48
```
49

50
## Basic Usage
51

52
```typescript
53
import { create } from "zustand";
54

55
// Define your store
56
interface BearState {
57
  bears: number;
58
  increase: (by: number) => void;
59
}
60

61
const useBearStore = create<BearState>((set) => ({
62
  bears: 0,
63
  increase: (by) => set((state) => ({ bears: state.bears + by })),
64
}));
65

66
// Use in React components
67
function BearCounter() {
68
  const bears = useBearStore((state) => state.bears);
69
  return <h1>{bears} around here ...</h1>;
70
}
71

72
function Controls() {
73
  const increasePopulation = useBearStore((state) => state.increase);
74
  return <button onClick={() => increasePopulation(1)}>one up</button>;
75
}
76
```
77

78
## Architecture
79

80
Zustand is built around several key components:
81

82
- **Vanilla Store**: Core state management engine that works without React
83
- **React Integration**: Hooks-based API using React's `useSyncExternalStore`
84
- **State Creator Pattern**: Function-based store initialization with TypeScript support
85
- **Middleware System**: Extensible middleware for devtools, persistence, and custom behaviors
86
- **Selector Pattern**: Efficient subscriptions to specific state slices
87
- **Mutator System**: Type-safe middleware composition with advanced TypeScript
88

89
## Capabilities
90

91
### Store Creation
92

93
Core functionality for creating and managing state stores, available in both React and vanilla JavaScript environments.
94

95
```typescript { .api }
96
function create<T, Mos extends [StoreMutatorIdentifier, unknown][] = []>(
97
  initializer: StateCreator<T, [], Mos>
98
): UseBoundStore<Mutate<StoreApi<T>, Mos>>;
99

100
function createStore<T, Mos extends [StoreMutatorIdentifier, unknown][] = []>(
101
  initializer: StateCreator<T, [], Mos>
102
): Mutate<StoreApi<T>, Mos>;
103

104
type StateCreator<T, Mis extends [StoreMutatorIdentifier, unknown][] = [], Mos extends [StoreMutatorIdentifier, unknown][] = [], U = T> = ((
105
  setState: Get<Mutate<StoreApi<T>, Mis>, 'setState', never>,
106
  getState: Get<Mutate<StoreApi<T>, Mis>, 'getState', never>,
107
  store: Mutate<StoreApi<T>, Mis>
108
) => U) & { $$storeMutators?: Mos };
109
```
110

111
[Store Creation](./store-creation.md)
112

113
### React Integration
114

115
React hooks and components for consuming Zustand stores with automatic re-rendering and selector support.
116

117
```typescript { .api }
118
function useStore<S extends ReadonlyStoreApi<unknown>>(api: S): ExtractState<S>;
119
function useStore<S extends ReadonlyStoreApi<unknown>, U>(
120
  api: S,
121
  selector: (state: ExtractState<S>) => U
122
): U;
123

124
type UseBoundStore<S extends ReadonlyStoreApi<unknown>> = {
125
  (): ExtractState<S>;
126
  <U>(selector: (state: ExtractState<S>) => U): U;
127
} & S;
128
```
129

130
[React Integration](./react-integration.md)
131

132
### Middleware
133

134
Extensible middleware system for adding DevTools integration, persistence, Redux-style actions, and custom behaviors.
135

136
```typescript { .api }
137
function devtools<T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = [], U = T>(
138
  initializer: StateCreator<T, [...Mps, ['zustand/devtools', never]], Mcs, U>,
139
  devtoolsOptions?: DevtoolsOptions
140
): StateCreator<T, Mps, [['zustand/devtools', never], ...Mcs]>;
141

142
function persist<T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = [], U = T>(
143
  initializer: StateCreator<T, [...Mps, ['zustand/persist', unknown]], Mcs>,
144
  options: PersistOptions<T, U>
145
): StateCreator<T, Mps, [['zustand/persist', U], ...Mcs]>;
146

147
function subscribeWithSelector<T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(
148
  initializer: StateCreator<T, [...Mps, ['zustand/subscribeWithSelector', never]], Mcs>
149
): StateCreator<T, Mps, [['zustand/subscribeWithSelector', never], ...Mcs]>;
150
```
151

152
[Middleware](./middleware.md)
153

154
### Utilities
155

156
Helper functions for shallow comparison, state combination, and traditional APIs with equality functions.
157

158
```typescript { .api }
159
function shallow<T>(valueA: T, valueB: T): boolean;
160
function useShallow<S, U>(selector: (state: S) => U): (state: S) => U;
161
function combine<T extends object, U extends object, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(
162
  initialState: T,
163
  create: StateCreator<T, Mps, Mcs, U>
164
): StateCreator<Write<T, U>, Mps, Mcs>;
165
```
166

167
[Utilities](./utilities.md)
168

169
### Traditional API
170

171
Alternative API for projects that need custom equality functions, providing compatibility with older patterns.
172

173
```typescript { .api }
174
function createWithEqualityFn<T, Mos extends [StoreMutatorIdentifier, unknown][] = []>(
175
  initializer: StateCreator<T, [], Mos>,
176
  defaultEqualityFn?: <U>(a: U, b: U) => boolean
177
): UseBoundStoreWithEqualityFn<Mutate<StoreApi<T>, Mos>>;
178

179
function useStoreWithEqualityFn<S extends ReadonlyStoreApi<unknown>>(
180
  api: S
181
): ExtractState<S>;
182

183
function useStoreWithEqualityFn<S extends ReadonlyStoreApi<unknown>, U>(
184
  api: S,
185
  selector: (state: ExtractState<S>) => U,
186
  equalityFn?: (a: U, b: U) => boolean
187
): U;
188
```
189

190
[React Integration](./react-integration.md)
191

192
## Core Types
193

194
```typescript { .api }
195
interface StoreApi<T> {
196
  setState: SetStateInternal<T>;
197
  getState: () => T;
198
  getInitialState: () => T;
199
  subscribe: (listener: (state: T, prevState: T) => void) => () => void;
200
}
201

202
type ExtractState<S> = S extends { getState: () => infer T } ? T : never;
203

204
interface StoreMutators<S, A> {}
205
type StoreMutatorIdentifier = keyof StoreMutators<unknown, unknown>;
206

207
type Mutate<S, Ms> = number extends Ms['length' & keyof Ms]
208
  ? S
209
  : Ms extends []
210
    ? S
211
    : Ms extends [[infer Mi, infer Ma], ...infer Mrs]
212
      ? Mutate<StoreMutators<S, Ma>[Mi & StoreMutatorIdentifier], Mrs>
213
      : never;
214

215
type UseBoundStoreWithEqualityFn<S extends ReadonlyStoreApi<unknown>> = {
216
  (): ExtractState<S>;
217
  <U>(
218
    selector: (state: ExtractState<S>) => U,
219
    equalityFn?: (a: U, b: U) => boolean
220
  ): U;
221
} & S;
222

223
type ReadonlyStoreApi<T> = Pick<StoreApi<T>, 'getState' | 'getInitialState' | 'subscribe'>;
224

225
type Write<T, U> = Omit<T, keyof U> & U;
226
```