# Selectors and rendering

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`](https://bench-zustand-61.atloria.app/p/bench-zustand-61-pSJCWrWW5Y/developer/zustand#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 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`](https://bench-zustand-61.atloria.app/p/bench-zustand-61-pSJCWrWW5Y/developer/zustand-react-shallow#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](https://bench-zustand-61.atloria.app/p/bench-zustand-61-pSJCWrWW5Y/developer/select-computed-state). For comparisons beyond shallow equality, see [Customize equality checks](https://bench-zustand-61.atloria.app/p/bench-zustand-61-pSJCWrWW5Y/developer/customize-equality-and-subscriptions).

## See selectors in a mounted React component

In the project from the [React quick start](https://bench-zustand-61.atloria.app/p/bench-zustand-61-pSJCWrWW5Y/developer/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](https://bench-zustand-61.atloria.app/p/bench-zustand-61-pSJCWrWW5Y/developer/store-and-react-binding#see-both-bindings-in-react) 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`](https://bench-zustand-61.atloria.app/p/bench-zustand-61-pSJCWrWW5Y/developer/zustand#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 title="src/count-store.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 title="src/SelectorExample.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](https://zustand-demo.pmnd.rs/) 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](https://bench-zustand-61.atloria.app/p/bench-zustand-61-pSJCWrWW5Y/developer/store-and-react-binding); for updating object references, see [Immutable state and merging](https://bench-zustand-61.atloria.app/p/bench-zustand-61-pSJCWrWW5Y/developer/immutable-state-and-merging).
