Skip to content
Tutorials Center
My learning

Topics

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.

JSX
const deferredQuery = useDeferredValue(query);

Try it

A responsive input with a lagging list

Results is wrapped in memo, so while the deferred value is unchanged it is skipped entirely.

Comparing live and deferred values

Check the console after one click: you see two renders, one with the old deferred number and one with the new.

Syntax

JSX
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 memo or useMemo on 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 !== deferredValue to 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 useTransition when you own the code that sets state; use useDeferredValue when you only receive a value (props, a third-party hook).