Read a vanilla store in React
A component consumes a store made with createStore rather than a bound React hook.
Zustand · Function
useStoreWithEqualityFn
useStoreWithEqualityFn connects a vanilla Zustand store to React while allowing a custom equality check. It is useful when a component needs selected store data and finer control over re-rendering.
How it works
This hook connects a vanilla Zustand store to a React component. It applies the selector to obtain the value exposed to the component, then uses the optional equality function to decide whether a changed selection warrants a re-render.
Syntax
useStoreWithEqualityFn<T, U = T>(store: StoreApi<T>, selectorFn: (state: T) => U, equalityFn?: (a: U, b: U) => boolean): UParameters
| Name | Type | Description |
|---|---|---|
storeApi | StoreApi<T> | The vanilla store API instance to read and subscribe to. |
selectorFn | (state: T) => U | Selects and returns data derived from the current store state. |
equalityFn | (a: U, b: U) => boolean | Optionally compares selected values; equal values can skip re-renders. |
Returns
The selected data derived from the current store state; the equality function can determine whether a re-render is skipped.
Key points
- Use it when a React component needs to read from a store created with Zustand's vanilla store API.
- The third argument lets the component control how successive selector results are compared.
- A suitable comparator can reduce unnecessary rendering while preserving updates that change the selected result.
- The first argument is the store API object, which supplies the hook with the vanilla store it should observe.
- The selector determines the data exposed to the component rather than requiring the component to consume the complete state.
- The equality function is used to decide whether a selected-value change requires rendering again.
Common mistakes
- When importing the hook from zustand/traditional, install the use-sync-external-store peer dependency first.
- Pass the store, selector, and equality function in that order; omitting or rearranging them does not match the documented call shape.
Example: Select from a vanilla store with shallow equality
import { createStore } from 'zustand/vanilla'
import { useStoreWithEqualityFn } from 'zustand/traditional'
import { shallow } from 'zustand/shallow'
type State = { bears: number; fish: number }
const store = createStore<State>(() => ({ bears: 0, fish: 0 }))
export function Counts() {
const counts = useStoreWithEqualityFn(
store,
(state) => ({ bears: state.bears, fish: state.fish }),
shallow,
)
return <div>{counts.bears} bears, {counts.fish} fish</div>
}Reads a selected object from a vanilla store and uses shallow comparison to avoid re-rendering when its selected values are unchanged.
When to use it
Compare grouped selections
A selector returns an object containing several fields and should avoid updates when those fields are unchanged.
Apply a custom render boundary
A frequently rendered component should update only when its selected data changes according to domain-specific comparison rules.
Interview questions
QWhat problem does useStoreWithEqualityFn solve?
It is a React Hook for consuming a vanilla Zustand store. Compared with useStore, it additionally accepts an equality function, which can prevent re-renders when the selected result is considered equal.
Follow-up: Why select a smaller value rather than the whole state? A narrower selection reduces the set of changes that can affect the component and makes equality checks more targeted.
QExplain the parameters and their roles.
The store argument is the StoreApi instance, selectorFn maps the current state to the value the component needs, and equalityFn compares successive selected values. The equality function is optional, so selection can still be used without a custom comparison.
Follow-up: What should an equality function compare? It should compare the selected values, not unrelated store state, and return true when the component can keep its existing rendered value.
QHow does the equality function affect rendering?
The hook returns the selector's current result. A component skips a re-render when the equality function reports that the previous and next selected results are equal.
Follow-up: How can a component select multiple fields as one object? Return an object from the selector and use an appropriate comparator such as shallow when that matches the desired comparison semantics.
Related
useStorecreateWithEqualityFncreateStoreshallow