Observe granular state changes
A vanilla or React-backed store needs a listener for one field or nested value.
Zustand · Function
subscribeWithSelector
subscribeWithSelector adds selector-based subscriptions to a Zustand store. Listeners can react to changes in selected data instead of observing unrelated state updates.
How it works
The middleware wraps a state creator and augments the store's subscribe API. A subscriber supplies a selector and a listener, so the listener runs when the selected portion of state updates rather than for every unrelated store change.
Syntax
subscribeWithSelector<T>(stateCreatorFn: StateCreator<T, [], []>): StateCreator<T, [['zustand/subscribeWithSelector', never]], []>Parameters
| Name | Type | Description |
|---|---|---|
stateCreatorFn | StateCreator<T, [], []> | A state-creator function receiving Zustand's set function, get function, and store; it usually returns the exposed state and methods. |
Returns
A state creator function with the subscribeWithSelector middleware mutator.
Key points
- Use it when a subscription should observe a specific state slice rather than the complete store.
- The middleware is applied by passing the existing state creator to subscribeWithSelector.
- The wrapped creator follows Zustand's normal state-creator contract and can use set, get, and store.
- The state creator normally returns the store's public state and actions.
- The subscription API is suitable for coordinating state with systems outside React.
Common mistakes
- The listener responds to updates of the selected slice, not necessarily to every complete-store update.
Example: Subscribe to a selected slice
import { createStore } from 'zustand/vanilla'
import { subscribeWithSelector } from 'zustand/middleware'
type PositionStore = {
position: { x: number; y: number }
setPosition: (position: { x: number; y: number }) => void
}
const store = createStore<PositionStore>()(
subscribeWithSelector((set) => ({
position: { x: 0, y: 0 },
setPosition: (position) => set({ position }),
})),
)
const unsubscribe = store.subscribe(
(state) => state.position,
(position) => console.log('position changed', position),
)
store.getState().setPosition({ x: 10, y: 20 })
unsubscribe()Creates a vanilla store whose subscription watches only the position slice and invokes the callback when that slice changes.
When to use it
Connect external systems
A store must notify a non-React integration when selected data changes.
Avoid irrelevant subscription callbacks
A large store has unrelated updates that should not trigger a particular listener.
Interview questions
QWhat problem does subscribeWithSelector solve?
It is a middleware that enables subscriptions to selected portions of a Zustand store. Instead of observing the entire state, a subscriber provides a selector and receives the selected value in its callback.
Follow-up: How can this support external state management? The documented pattern is to use the store's subscribe API outside React and react to selected state changes there.
QWhat does the middleware accept and return?
Its state creator accepts the usual set, get, and store arguments and returns a state creator with the subscribeWithSelector mutator. Applying it augments the store subscription behavior without changing the state shape exposed by the creator.
Follow-up: What does the middleware return? It returns a state creator function, which is then passed into store creation.
QWhat is its TypeScript signature?
The documented signature is subscribeWithSelector<T>(stateCreatorFn: StateCreator<T, [], []>): StateCreator<T, [['zustand/subscribeWithSelector', never]], []>. The input is a state-creator function, and the result is another state creator carrying the middleware mutator type.
Follow-up: Why does the mutator appear in the TypeScript result? It records the middleware transformation in Zustand's state-creator typing.
Related
subscribecreateStoreStateCreatorzustand/middleware