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.
const deferred = useDeferredValue(searchText, '');
Try it
The console shows a first render with deferred="" and a second with deferred="react".
Here rows keeps the same reference between renders, so deferredRows !== rows is true only during the placeholder pass.
Syntax
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,
initialValueis never used again; remounting (for example by changingkey) 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.initialValueis read only on the first render, so writing a new[]or{}literal inline does no harm. Thevalueargument is different: it must stay referentially stable between renders. - Availability: React 19 and later; older versions ignore the argument or fail type checks.
Related
useDeferredValue,useTransition,<Suspense>- Lessons: Transitions