Optimize selector-driven rendering
A component selects a derived object or array and should not re-render when its relevant contents are unchanged.
Zustand · Pipe
equalityFn
createWithEqualityFn creates a React hook like create but adds configurable equality checking for selector results. Use it to avoid re-renders when a selected value is considered equal by the comparator.
How it works
createWithEqualityFn creates a React hook like create, while allowing a default equality function for selector results. The equality check determines whether a selected value is considered changed, so unchanged selections can avoid component re-renders.
Syntax
createWithEqualityFn<T>()(stateCreatorFn: StateCreator<T, [], []>, defaultEqualityFn?: <U>(a: U, b: U) => boolean): UseBoundStore<StoreApi<T>>Parameters
| Name | Type | Description |
|---|---|---|
stateCreatorFn | StateCreator<T, [], []> | Function receiving set, get, and store; it normally returns the state and actions exposed by the hook. |
defaultEqualityFn | <U>(a: U, b: U) => boolean | Optional comparator for selected values; it defaults to Object.is and can prevent re-renders when values compare equal. |
Returns
A React hook with API utilities attached, allowing selector results to be compared with an equality function.
Key points
- The function creates a bound React hook and exposes the store API utilities.
- A custom equality check can be supplied for comparing selected results.
- Equality customization gives finer control over when subscribed components re-render.
- The state creator commonly returns the state values and actions that the hook exposes.
- The optional default equality function decides when a selector result does not require another render.
Common mistakes
- The traditional entry point requires the use-sync-external-store package.
Example: Using a custom equality function
import { createWithEqualityFn } from 'zustand/traditional'
import { shallow } from 'zustand/shallow'
const useBearStore = createWithEqualityFn(() => ({ bears: 0 }))
export function Bears() {
const bears = useBearStore((state) => state.bears, Object.is)
const selection = useBearStore(
(state) => ({ bears: state.bears }),
shallow,
)
return <>{bears} {selection.bears}</>
}Creates a store whose selector subscriptions can use an equality function, including the default Object.is or shallow comparison.
When to use it
Set a store-wide equality policy
A store needs a comparison policy applied by default to its React-hook subscriptions.
Migrate custom equality behavior
A v5 application previously relied on custom equality behavior supported by an older create setup.
Interview questions
QWhat does createWithEqualityFn add compared with create?
createWithEqualityFn returns a React hook with the store API utilities attached, similar to create. Its additional capability is a default equality function that can skip re-renders when selected results compare equal.
Follow-up: How can a selector use a different comparison? Pass an equality function with the selector when reading from the store.
QWhat are its main arguments and default behavior?
The signature is createWithEqualityFn<T>()(stateCreatorFn, defaultEqualityFn?). The state creator receives set, get, and the store, while the optional equality function defaults to Object.is.
Follow-up: Why might a caller choose shallow? It can compare simple object selections so equivalent selected fields do not trigger another render.
QHow does equalityFn affect rendering?
An equality function receives two selected values and returns a boolean. Returning true means the values are equal for subscription purposes, allowing the hook to skip a re-render.
Follow-up: What is the v5 alternative to customizing equality on create? Use createWithEqualityFn, or use useShallow for the shallow-comparison case.
Related
createuseStoreWithEqualityFnshallowuseShallowsubscribeWithSelector