React Reference ยท Performance and Concurrency Hooks
React useDeferredValue hook
Reference for React useDeferredValue: keep an input responsive by letting a slow part of the UI lag behind with an older value, with examples and caveats.
useDeferredValue gives you a copy of a value that may lag behind the real one. When the real value changes, React first re-renders with the old deferred value (a fast update), then re-renders again in the background with the new one. If the user keeps typing, the background render is thrown away and restarted.
The classic use is search-as-you-type: the input updates immediately from the live state, while the expensive results list reads the deferred state. You get responsiveness without writing a debounce timer.
const deferredQuery = useDeferredValue(query);
Try it
Results is wrapped in memo, so while the deferred value is unchanged it is skipped entirely.
Check the console after one click: you see two renders, one with the old deferred number and one with the new.
Syntax
const deferredValue = useDeferredValue(value); const deferredValue = useDeferredValue(value, initialValue); // React 19 // TypeScript: useDeferredValue<T>(value: T, initialValue?: T): T
| Name | Description |
|---|---|
value |
The value to defer. Primitives, or objects created outside render. |
initialValue |
Optional (React 19). Returned on the very first render; see useDeferredValue initial value. |
Returns: during the initial render, the value you passed (or initialValue). During updates, the previous value until React finishes the background render with the new one.
Usage notes
- Pair it with
memooruseMemoon the slow part; otherwise the child re-renders for the old value anyway and nothing is saved. - Pass primitives or stable objects. A new object created in render differs every time, so the deferred render never settles and loops.
- Show staleness. Compare
value !== deferredValueto dim the content or show a hint. - Not a network debounce. The deferral is about rendering work, not about requests: no delay is added. A request keyed by the deferred value still fires once per background render.
- Interruptible. Rendering with the deferred value can be dropped midway if a newer value arrives.
- Suspense: if the deferred render suspends, the previous UI stays visible instead of a fallback.
- Choosing between hooks: use
useTransitionwhen you own the code that sets state; useuseDeferredValuewhen you only receive a value (props, a third-party hook).