Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Performance and Concurrency Hooks

React useDeferredValue initial value

Learn the second argument of useDeferredValue in React 19: show a placeholder value on the first render and let the real value arrive in the background.

React 19 added an optional second argument to useDeferredValue: initialValue. On the component's very first render the hook returns that initial value instead of the real one. Immediately afterwards React schedules a background re-render that uses the real value.

Why? Without it, a heavy component whose input is known up front blocks the first paint. With a cheap initialValue (often an empty string) the page appears at once and the expensive content fills in right behind it, without you writing an effect.

JSX
const deferred = useDeferredValue(searchText, '');

Try it

Watching the two renders

The console shows a first render with deferred="" and a second with deferred="react".

Cheap shell first, expensive list second

Here rows keeps the same reference between renders, so deferredRows !== rows is true only during the placeholder pass.

Syntax

JSX
const deferredValue = useDeferredValue(value, initialValue);
Name Description
value The real value that will eventually be returned.
initialValue Returned on the first render only. Not used again for the same component instance.

Returns: initialValue during the first render, then value after the background render commits. Later changes to value behave like normal deferral.

Edge cases: if you omit the second argument, the first render returns value directly (React 18 behavior).

Usage notes

  • Only the first render. After mount, initialValue is never used again; remounting (for example by changing key) brings it back.
  • Server rendering: during hydration and server render the component renders with initialValue, then updates; this keeps the first HTML light.
  • Pick a cheap placeholder that your children can render, such as '', [] or a minimal object. The children must tolerate it.
  • It is not a loading state from the network. Nothing is fetched; React just renders twice.
  • A fresh [] is fine here. initialValue is read only on the first render, so writing a new [] or {} literal inline does no harm. The value argument is different: it must stay referentially stable between renders.
  • Availability: React 19 and later; older versions ignore the argument or fail type checks.