A selector is a function that reads the value your component needs from a store; equality of that value determines whether a store update triggers a re-render.
The hook returned by create binds a store to React without a context provider. Select a field or computed value rather than the whole state when your component only needs part of the store.
From a state update to a render
Zustand keeps state independently of React. An update through set merges the supplied top-level fields and notifies the store's listeners. The React hook reads its selector's output as an external-store snapshot, which React compares with Object.is.
mermaidflowchart TD A["Action calls set"] --> B["Store updates state and notifies listeners"] B --> C["Hook reads selector output"] C --> D{"Output equal by Object.is?"} D -->|Yes| E["No render triggered by this store update"] D -->|No| F["React renders the subscribing component"]
The selector does not create a separate store or a field-specific listener. It determines the snapshot your component consumes. These are different boundaries:
| What you select | What equality compares | When a store update triggers a render |
|---|---|---|
| The whole state, by calling the hook without a selector | The state object's identity | When the state object changes, including updates to fields you do not display |
| A primitive field or computed primitive | Its value, using Object.is | When the selected value changes |
| An existing object or function in state | Its reference | When that reference changes |
A computed object or array wrapped with useShallow | Its shallow contents, with the previous output reference reused when equal | When the shallow contents change |
These checks govern renders caused by the store subscription. They do not prevent React from rendering a component because its parent, props, or local state changes.
Output identity and shallow equality
useShallow takes a selector and returns a selector that retains the previous output when the new output is shallow-equal. Pass the returned selector to your store hook.
For a plain object, shallow equality compares its top-level keys and their values with Object.is; for an array, it compares indexed values. It does not recursively compare nested objects. This lets you group several state picks in one object or array while retaining a stable output reference when those picks remain equal.
The wrapper still runs your selector to compute the next output. It memoizes the output reference, not the computation. For example, a computed count can change while a selected parity value remains the same; a component that selects only parity does not need that count update to trigger a render.
For the constraints on newly allocated selector outputs in v5, see Select computed state. For comparisons beyond shallow equality, see Customize equality checks.
See selectors in a mounted React component
In the project from the React quick start, add the following two files to compare independent and grouped selections, then add import SelectorExample from './SelectorExample' to your app component and render <SelectorExample /> in its existing JSX; see Stores and React bindings for the mounting setup.
Outside that project, install both dependencies; react is an optional peer dependency of zustand and is required by zustand/react/shallow. The quick-start project already has both, so it needs no additional install.
bashnpm install zustand react
useStore also accepts a store API and a selector. The summary below passes the bound hook's store API to it and wraps its selector with useShallow.
The example displays a count, its doubled value, and a separate note. Increment and decrement update the count panels. Changing the note updates only the note's selected value: the counter's primitive selections and the summary's shallow-equal output remain unchanged.
tsimport { create } from 'zustand'
type CountStore = {
count: number
note: string
increment: (qty: number) => void
decrement: (qty: number) => void
toggleNote: () => void
}
export const useCountStore = create<CountStore>()((set) => ({
count: 0,
note: 'Ready',
increment: (qty) => set((state) => ({ count: state.count + qty })),
decrement: (qty) => set((state) => ({ count: state.count - qty })),
toggleNote: () =>
set((state) => ({
note: state.note === 'Ready' ? 'Note changed' : 'Ready',
})),
}))
tsximport { useStore } from 'zustand'
import { useShallow } from 'zustand/react/shallow'
import { useCountStore } from './count-store'
function Counter() {
const count = useCountStore((state) => state.count)
const increment = useCountStore((state) => state.increment)
const decrement = useCountStore((state) => state.decrement)
return (
<section>
<h2>Individual selections</h2>
<p>Count: {count}</p>
<button onClick={() => increment(1)}>Increment</button>
<button onClick={() => decrement(1)}>Decrement</button>
</section>
)
}
function Summary() {
const { count, doubled } = useStore(
useCountStore,
useShallow((state) => ({
count: state.count,
doubled: state.count * 2,
})),
)
return (
<section>
<h2>Grouped selections</h2>
<p>Count: {count}; doubled: {doubled}</p>
</section>
)
}
function Note() {
const note = useCountStore((state) => state.note)
const toggleNote = useCountStore((state) => state.toggleNote)
return (
<section>
<h2>Independent selection</h2>
<p>{note}</p>
<button onClick={toggleNote}>Change note</button>
</section>
)
}
export default function SelectorExample() {
return (
<main>
<h1>Selectors and rendering</h1>
<Counter />
<Summary />
<Note />
</main>
)
}
Initially, both count panels show 0, the doubled value is 0, and the note reads Ready. Use React DevTools' Profiler to inspect which components render as you click each button; unchanged displayed text alone does not prove that a component skipped a render.
Counter subscribes separately to count, increment, and decrement, following the authors' selector example. The actions retain their references when set merges a count or note update. Summary computes a new object on each selector call, but useShallow returns its previous object when both numbers remain equal. SelectorExample itself does not read the store, so these store subscriptions live in its children.
How this compares with Redux
Zustand and Redux both use an immutable state model. Use selectors for render optimization in both libraries. In Zustand, select data and actions through the bound store hook, as Counter does above; no context provider is required. You can colocate actions with state without introducing a reducer or dispatched action objects.
The important choice is what the component consumes, not how many fields the store holds. Selecting the whole state and then destructuring it still consumes the whole-state snapshot. Selecting a field inside the selector narrows the snapshot before React compares it.
Try the authors' live counter demo to see a bound store hook drive a rendered counter. For the relationship between vanilla stores and React hooks, continue with Stores and React bindings; for updating object references, see Immutable state and merging.
Was this page helpful?