Keep typing responsive
A controlled search input updates immediately while an expensive results list consumes a deferred query.
React 19+ · Hook
useDeferredValue
useDeferredValue lets you defer updating a non-critical part of the UI so urgent updates can appear first. It returns a value that may temporarily lag behind the latest input.
- Since
- React 19
How it works
Call this Hook with a value at the top level of a component. React returns the current value initially, then may render with the previous value first and retry in the background with the new value, allowing urgent UI such as typing to update before slower content.
Syntax
const deferredValue = useDeferredValue(value, initialValue?)Parameters
| Name | Type | Description |
|---|---|---|
value | any | The value to defer; it can have any type. |
initialValue | any | Optional value used during the component's initial render. Without it, the initial render is not deferred. |
Returns
The current deferred value: initially initialValue when supplied, otherwise the provided value; during updates it may remain the old value before switching to the new value after background rendering.
Key points
- Use it when a non-critical UI region should update after more urgent parts, such as an input.
- Invoke it at component top level and store the returned value for the slower subtree or calculation.
- The consumer can temporarily display content based on the previous value while React prepares the fresh result.
- React follows the initial update with background work that uses the latest value.
- Supplying initialValue lets the first render use a fallback-like value before the deferred input is applied.
Common mistakes
- Prefer primitives or objects created outside rendering; creating a new object during rendering can trigger unnecessary background work.
Example: Responsive search
import { useDeferredValue, useState } from 'react';
export default function Search({ items }: { items: string[] }) {
const [query, setQuery] = useState('');
const deferredQuery = useDeferredValue(query);
const results = items.filter(item =>
item.toLowerCase().includes(deferredQuery.toLowerCase())
);
return (
<>
<label>
Search: <input value={query} onChange={e => setQuery(e.target.value)} />
</label>
<ul>{results.map(item => <li key={item}>{item}</li>)}</ul>
</>
);
}The input responds immediately while filtering can continue with the deferred query.
When to use it
Show stale content during loading
A Suspense-backed result view continues using the previous query while fresh content loads.
Defer expensive rendering
A large derived view recalculates from a deferred primitive, allowing higher-priority interactions to proceed.
Interview questions
QHow does useDeferredValue affect rendering?
It returns a deferred version of the supplied value. On updates, React can first render with the old value and then attempt a background render using the new one, keeping urgent UI responsive.
Follow-up: How does it differ from debouncing? React does not use a fixed delay; the background render is interruptible and does not block user input.
QWhat is initialValue for?
The optional initialValue is used for the component's initial render. If omitted, the Hook does not defer that first render because no previous value exists.
Follow-up: What happens after the initial render? React schedules work with the supplied value so the component can update in the background.
QWhat values should be passed to the Hook?
The Hook compares the incoming value with the previous one using Object.is. Values should therefore be primitives or stable objects created outside rendering.
Follow-up: Why is an inline object problematic? A newly created object differs on every render, which can cause unnecessary background renders.
Related
useTransitionstartTransition<Suspense>useState