const deferredQuery = useDeferredValue(query) gives you a copy of query that is allowed to lag behind. When query changes:
- React renders urgently with the old deferred value. The input shows the new keystroke right away; a
memochild that receivesdeferredQuerysees unchanged props and is skipped. - React then renders again in the background with the new value, at Transition priority. If another keystroke arrives first, that render is abandoned and restarted with the newest value.
Compared with debouncing:
- No fixed delay. A debounce waits a chosen number of milliseconds after the last call, on every device. The deferred render starts as soon as the urgent one has committed, so on a fast machine the lag is barely visible and on a slow one it grows with the work.
- Interruptible. A debounced update still renders in one block when it fires, and input during that render waits. The deferred render yields between components and gives way to input.
- Different target.
useDeferredValuedefers rendering. It doesn't stop work outside rendering: a fetch per keystroke still happens. Debouncing or throttling is still the tool for requests, and the two combine.
Two requirements make it work. The slow part must be a separate memoized component that receives only the deferred value; without memo, the urgent render re-renders it anyway. And the value should be a primitive or an object created outside rendering, since a fresh object every render always differs (by Object.is) and schedules a background render each time.
Use it when you don't own the setter, such as a value arriving as a prop; with the setter, startTransition does the same job. Show staleness by comparing query !== deferredQuery. React 19 added an optional initialValue, rendered first on mount before the real value.