---
name: zustand-store-patterns
user-invocable: false
description: Use when creating and managing Zustand stores for React state management. Covers store creation, selectors, actions, and basic usage patterns.
allowed-tools:
- Read
- Write
- Edit
- Bash
- Grep
- Glob
---
# Zustand - Store Patterns
Zustand is a small, fast, and scalable state management solution for React. It uses a simplified flux principles with a hooks-based API.
## Key Concepts
### Store Creation
A Zustand store is created using the `create` function:
```typescript
import { create } from 'zustand'
interface BearStore {
bears: number
increasePopulation: () => void
removeAllBears: () => void
}
const useBearStore = create<BearStore>((set) => ({
bears: 0,
increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
removeAllBears: () => set({ bears: 0 }),
}))
```
### Using the Store in Components
```typescript
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}>Add bear</button>
}
```
### State Updates
Zustand provides two ways to update state:
```typescript
// Replace state
set({ bears: 5 })
// Merge state (shallow merge)
set((state) => ({ bears: state.bears + 1 }))
```
## Best Practices
### 1. Use Selectors for Performance
Select only the state you need to prevent unnecessary re-renders:
```typescript
// ❌ Bad: Component re-renders on any state change
function BadComponent() {
const store = useBearStore()
return <div>{store.bears}</div>
}
// ✅ Good: Component only re-renders when bears changes
function GoodComponent() {
const bears = useBearStore((state) => state.bears)
return <div>{bears}</div>
}
```
### 2. Separate Actions from State
Keep your store organized by separating data from actions:
```typescript
interface TodoStore {
// State
todos: Todo[]
filter: 'all' | 'active' | 'completed'
// Actions
addTodo: (text: string) => void
toggleTodo: (id: string) => void
removeTodo: (id: string) => void
setFilter: (filter: TodoStore['filter']) => void
}
const useTodoStore = create<TodoStore>((set) => ({
todos: [],
filter: 'all',
addTodo: (text) =>
set((state) => ({
todos: [...state.todos, { id: Date.now().toString(), text, completed: false }],
})),
toggleTodo: (id) =>
set((state) => ({
todos: state.todos.map((todo) =>
todo.id === id ? { ...todo, completed: !todo.completed } : todo
),
})),
removeTodo: (id) =>
set((state) => ({
todos: state.todos.filter((todo) => todo.id !== id),
})),
setFilter: (filter) => set({ filter }),
}))
```
### 3. Use Shallow Equality for Multiple Selectors
When selecting multiple values, use `shallow` from `zustand/shallow`:
```typescript
import { create } from 'zustand'
import { shallow } from 'zustand/shallow'
const useStore = create<Store>((set) => ({
nuts: 0,
honey: 0,
increaseNuts: () => set((state) => ({ nuts: state.nuts + 1 })),
increaseHoney: () => set((state) => ({ honey: state.honey + 1 })),
}))
// ✅ Using shallow comparison
function Component() {
const { nuts, honey } = useStore(
(state) => ({ nuts: state.nuts, honey: state.honey }),
shallow
)
return <div>{nuts} nuts, {honey} honey</div>
}
```
### 4. Organize Large Stores with Slices
For complex applications, split stores into logical slices:
```typescript
interface UserSlice {
user: User | null
login: (credentials: Credentials) => Promise<void>
logout: () => void
}
interface CartSlice {
items: CartItem[]
addItem: (item: Product) => void
removeItem: (id: string) => void
clearCart: () => void
}
const createUserSlice = (set: StateCreator<UserSlice>) => ({
user: null,
login: async (credentials) => {
const user = await api.login(credentials)
set({ user })
},
logout: () => set({ user: null }),
})
const createCartSlice = (set: StateCreator<CartSlice>) => ({
items: [],
addItem: (product) =>
set((state) => ({
items: [...state.items, { ...product, quantity: 1 }],
})),
removeItem: (id) =>
set((state) => ({
items: state.items.filter((item) => item.id !== id),
})),
clearCart: () => set({ items: [] }),
})
const useStore = create<UserSlice & CartSlice>()((...a) => ({
...createUserSlice(...a),
...createCartSlice(...a),
}))
```
### 5. Access Store Outside Components
Use `getState` and `setState` for non-reactive access:
```typescript
const useBearStore = create<BearStore>((set, get) => ({
bears: 0,
increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
doSomething: () => {
const currentBears = get().bears
console.log(`Current bears: ${currentBears}`)
},
}))
// Outside components
const currentState = useBearStore.getState()
useBearStore.setState({ bears: 10 })
```
## Examples
### Simple Counter Store
```typescript
import { create } from 'zustand'
interface CounterStore {
count: number
increment: () => void
decrement: () => void
reset: () => void
}
export const useCounterStore = create<CounterStore>((set) => ({
count: 0,
increment: () => set((state) => ({ count: state.count + 1 })),
decrement: () => set((state) => ({ count: state.count - 1 })),
reset: () => set({ count: 0 }),
}))
// Usage
function Counter() {
const { count, increment, decrement, reset } = useCounterStore()
return (
<div>
<h1>Count: {count}</h1>
<button onClick={increment}>+</button>
<button onClick={decrement}>-</button>
<button onClick={reset}>Reset</button>
</div>
)
}
```
### Shopping Cart Store
```typescript
import { create } from 'zustand'
interface CartItem {
id: string
name: string
price: number
quantity: number
}
interface CartStore {
items: CartItem[]
addItem: (product: Omit<CartItem, 'quantity'>) => void
removeItem: (id: string) => void
updateQuantity: (id: string, quantity: number) => void
clearCart: () => void
total: number
}
export const useCartStore = create<CartStore>((set, get) => ({
items: [],
addItem: (product) =>
set((state) => {
const existingItem = state.items.find((item) => item.id === product.id)
if (existingItem) {
return {
items: state.items.map((item) =>
item.id === product.id
? { ...item, quantity: item.quantity + 1 }
: item
),
}
}
return {
items: [...state.items, { ...product, quantity: 1 }],
}
}),
removeItem: (id) =>
set((state) => ({
items: state.items.filter((item) => item.id !== id),
})),
updateQuantity: (id, quantity) =>
set((state) => ({
items: state.items.map((item) =>
item.id === id ? { ...item, quantity } : item
),
})),
clearCart: () => set({ items: [] }),
get total() {
return get().items.reduce(
(sum, item) => sum + item.price * item.quantity,
0
)
},
}))
```
### Authentication Store
```typescript
import { create } from 'zustand'
interface User {
id: string
email: string
name: string
}
interface AuthStore {
user: User | null
token: string | null
isLoading: boolean
error: string | null
login: (email: string, password: string) => Promise<void>
logout: () => void
checkAuth: () => Promise<void>
}
export const useAuthStore = create<AuthStore>((set) => ({
user: null,
token: null,
isLoading: false,
error: null,
login: async (email, password) => {
set({ isLoading: true, error: null })
try {
const response = await fetch('/api/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, password }),
})
if (!response.ok) {
throw new Error('Login failed')
}
const { user, token } = await response.json()
set({ user, token, isLoading: false })
localStorage.setItem('token', token)
} catch (error) {
set({
error: error instanceof Error ? error.message : 'Login failed',
isLoading: false,
})
}
},
logout: () => {
localStorage.removeItem('token')
set({ user: null, token: null })
},
checkAuth: async () => {
const token = localStorage.getItem('token')
if (!token) return
set({ isLoading: true })
try {
const response = await fetch('/api/me', {
headers: { Authorization: `Bearer ${token}` },
})
if (!response.ok) {
throw new Error('Auth check failed')
}
const user = await response.json()
set({ user, token, isLoading: false })
} catch (error) {
localStorage.removeItem('token')
set({ user: null, token: null, isLoading: false })
}
},
}))
```
## Common Patterns
### Computed Values
Use getters for derived state:
```typescript
const useStore = create<Store>((set, get) => ({
items: [],
get itemCount() {
return get().items.length
},
get hasItems() {
return get().items.length > 0
},
}))
```
### Async Actions
Handle async operations within actions:
```typescript
const useStore = create<Store>((set) => ({
data: null,
isLoading: false,
error: null,
fetchData: async () => {
set({ isLoading: true, error: null })
try {
const data = await api.fetchData()
set({ data, isLoading: false })
} catch (error) {
set({ error: error.message, isLoading: false })
}
},
}))
```
### Reset Store
Implement a reset action:
```typescript
const initialState = {
count: 0,
name: '',
}
const useStore = create<Store>((set) => ({
...initialState,
increment: () => set((state) => ({ count: state.count + 1 })),
setName: (name: string) => set({ name }),
reset: () => set(initialState),
}))
```
## Anti-Patterns
### ❌ Don't Mutate State Directly
```typescript
// Bad
const useStore = create((set) => ({
items: [],
addItem: (item) => {
// DON'T mutate state directly
items.push(item)
},
}))
// Good
const useStore = create((set) => ({
items: [],
addItem: (item) =>
set((state) => ({
items: [...state.items, item],
})),
}))
```
### ❌ Don't Select the Entire Store
```typescript
// Bad: Causes re-render on any state change
const store = useStore()
// Good: Select only what you need
const count = useStore((state) => state.count)
```
### ❌ Don't Use External State in Selectors
```typescript
// Bad: Selector depends on external value
const [userId, setUserId] = useState('123')
const user = useStore((state) => state.users[userId])
// Good: Pass external values as arguments
const getUser = (userId: string) => useStore.getState().users[userId]
```
### ❌ Don't Create Multiple Stores for Related Data
```typescript
// Bad: Splitting related state across stores
const useUserStore = create(...)
const useUserSettingsStore = create(...)
const useUserPreferencesStore = create(...)
// Good: Keep related state together
const useUserStore = create((set) => ({
profile: null,
settings: {},
preferences: {},
}))
```
## Related Skills
- **zustand-typescript**: TypeScript integration and type safety patterns
- **zustand-middleware**: Using persist, devtools, and immer middleware
- **zustand-advanced-patterns**: Subscriptions, transient updates, and advanced techniques