Skip to content
D
Documentation

Selectors and rendering

concept
4 min readUpdated

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.

mermaid
flowchart 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 selectWhat equality comparesWhen a store update triggers a render
The whole state, by calling the hook without a selectorThe state object's identityWhen the state object changes, including updates to fields you do not display
A primitive field or computed primitiveIts value, using Object.isWhen the selected value changes
An existing object or function in stateIts referenceWhen that reference changes
A computed object or array wrapped with useShallowIts shallow contents, with the previous output reference reused when equalWhen 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.

bash
npm 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.

ts
import { 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',
    })),
}))
tsx
import { 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?

Selectors and rendering — zustand · GPT-6.1 Sol