Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

React useTransition and useDeferredValue: Non-Blocking Concurrent UI Updates

Transitions let React throw away background work when typing arrives. Which hook defers what, and why a controlled input must never be transitioned.

~5 min readReact
#React#Concurrency#Performance
3D illustration of urgent typing input lanes prioritized ahead of interruptible background transition renders

Quick Summary

A transition marks a state update as interruptible. React renders it in the background, yields to anything urgent that arrives — a keystroke, a click, a hover — and throws away the partial work if the value changes again. useTransition gives you a function to wrap the update and a boolean that says whether the background render is still running. useDeferredValue does the same thing from the other side: instead of wrapping the setter, you hand React a value and get back a lagging copy that is allowed to render late.

The distinction that decides which one you need is who owns the update. If your component calls the setState that triggers the expensive render, wrap it in startTransition. If the value arrives as a prop, from a context, or from a library you do not control, defer it with useDeferredValue — you have nothing to wrap.

Neither hook makes work faster. They make the interface responsive by choosing which work can be interrupted, which is a scheduling decision, not an optimisation. A 400 ms render is still 400 ms; the difference is that typing no longer waits behind it.

Basic Syntax & Signature

tsx
import { useDeferredValue, useTransition } from "react"; function SearchBox({ onQuery }: { onQuery: (q: string) => void }) { const [query, setQuery] = useState(""); const [isPending, startTransition] = useTransition(); function onChange(e: React.ChangeEvent<HTMLInputElement>) { // The input update stays urgent: the caret must never lag. setQuery(e.target.value); // The expensive consumer is deprioritised and can be interrupted. startTransition(() => { onQuery(e.target.value); }); } return ( <> <input value={query} onChange={onChange} /> {isPending && <span aria-hidden>searching…</span>} </> ); }

useTransition() takes no arguments and returns a tuple: the pending flag, and a function that accepts a synchronous callback (React 19 also accepts an async function, see below). The callback must contain state updates; work performed outside a state update is not scheduled by React and cannot be interrupted.

useDeferredValue has the mirrored shape:

tsx
function Results({ query }: { query: string }) { // Deferred copy: lags behind `query` during fast typing. const deferredQuery = useDeferredValue(query); const isStale = query !== deferredQuery; return ( <div style={{ opacity: isStale ? 0.6 : 1 }}> <ExpensiveList query={deferredQuery} /> </div> ); }

React 19 adds an optional second argument used only for the very first render, which matters on a server-rendered page where deferring would otherwise mean rendering the stale value first:

tsx
const deferredQuery = useDeferredValue(query, ""); // initial render uses ""

React 19 also makes transitions async-aware, which is how form submissions integrate with pending state:

tsx
const [isPending, startTransition] = useTransition(); function save() { startTransition(async () => { // isPending stays true across the await in React 19. await updateProfile(formData); setProfile(await refreshProfile()); }); }

Key Comparison Table

SituationuseTransitionuseDeferredValue
You own the setStateYesNot needed
Value arrives as a propCannot wrap itYes
Returns[isPending, startTransition]Deferred value
Pending indicatorisPendingvalue !== deferredValue
InterruptibleYesYes
Initial-render controlNoinitialValue argument
Works with async workReact 19: yesNo (it defers values, not promises)
Typical targetExpensive state updateExpensive child render
Can wrap a controlled input updateTechnically yes, but wrongNot applicable
Suspense integrationTransitions suppress fallbacksBackground render never shows fallbacks

Practical Edge Cases & Deep Dives

1. The controlled input that must not be transitioned

tsx
function BrokenSearch() { const [query, setQuery] = useState(""); const [isPending, startTransition] = useTransition(); return ( <input value={query} onChange={(e) => { // Wrong: the input's own value is a transition, so the caret and the // characters trail behind typing and React may discard the update. startTransition(() => setQuery(e.target.value)); }} /> ); }

A transition is allowed to be thrown away, and a controlled input whose value was thrown away snaps back to the previous string. The controlled value must be set urgently; only the derived work goes into the transition. Two states, or useDeferredValue on query, both keep the input at full speed while the list renders late.

2. Filtering a large list without a spinner

tsx
const ITEMS = Array.from({ length: 20000 }, (_, i) => `item-${i}`); function Filter() { const [query, setQuery] = useState(""); const deferred = useDeferredValue(query); const isStale = query !== deferred; const filtered = useMemo( () => ITEMS.filter((i) => i.includes(deferred)), [deferred] ); return ( <section> <input value={query} onChange={(e) => setQuery(e.target.value)} /> <ul style={{ opacity: isStale ? 0.5 : 1, transition: "opacity 120ms" }}> {filtered.slice(0, 200).map((i) => <li key={i}>{i}</li>)} </ul> </section> ); }

The stale dimming is the standard affordance: the list keeps showing old results instead of an empty loading state. useMemo matters here because the filter itself is the expensive part and it keys off the deferred value, so it only recomputes when the background render commits.

3. A tab switch that finishes without a blank screen

tsx
function Tabs() { const [tab, setTab] = useState<"chart" | "table">("chart"); const [isPending, startTransition] = useTransition(); return ( <div> {(["chart", "table"] as const).map((name) => ( <button key={name} aria-selected={tab === name} onClick={() => startTransition(() => setTab(name))} > {name} {isPending && tab !== name ? "…" : ""} </button> ))} <div style={{ opacity: isPending ? 0.6 : 1 }}> {tab === "chart" ? <Chart /> : <DataTable />} </div> </div> ); }

React only shows a Suspense fallback when an update is urgent. Inside a transition, a suspending component keeps the previous UI on screen until the new data arrives, so tab switches stop flashing empty panels. This behaviour is the strongest argument for transitions in data-driven UIs, independent of any CPU savings.

4. Two inputs, one urgent writer

tsx
function CommentComposer() { const [text, setText] = useState(""); const deferredText = useDeferredValue(text); const lines = useMemo(() => deferredText.split("\n").length, [deferredText]); const words = useMemo(() => deferredText.trim().split(/\s+/).filter(Boolean).length, [deferredText]); return ( <form> <textarea value={text} onChange={(e) => setText(e.target.value)} /> <p aria-live="polite"> {words} words · {lines} lines {text !== deferredText ? "(updating)" : ""} </p> </form> ); }

The textarea keeps its own value, and the counters read the deferred one. Counting words in a 30,000-character draft on every keystroke is the classic case where the cheap input update must not be coupled to the expensive derived render.

5. Async transitions and pending state that survives await

tsx
function LikeButton({ postId, liked }: { postId: string; liked: boolean }) { const [isPending, startTransition] = useTransition(); const [state, setState] = useState(liked); return ( <button disabled={isPending} onClick={() => { startTransition(async () => { const next = !state; setState(next); // may suspend; transition keeps the old UI visible await fetch(`/api/posts/${postId}/like`, { method: "POST", body: JSON.stringify({ liked: next }), }); }); }} > {isPending ? "saving…" : state ? "liked" : "like"} </button> ); }

In React 18 an async callback silently lost the transition after the first await, because the pending scope ended when the synchronous part returned. React 19 keeps the transition open until the returned promise settles, which is why async actions show a stable pending state. On React 18, the same code needs a manual pending state or a mutation library.

6. Measuring whether the transition helped

tsx
function useRenderCount(label: string) { const count = useRef(0); count.current += 1; useEffect(() => { console.debug(`${label} render #${count.current}`, performance.now().toFixed(1)); }); } function HeavyPanel({ query }: { query: string }) { useRenderCount("HeavyPanel"); const deferred = useDeferredValue(query); // Without the deferral this render would run on every keystroke. return <List query={deferred} />; }

A transition that helps should reduce the number of renders of the expensive child, not just move them. If the child still renders on every keystroke, the expensive work is probably upstream of the deferred value, or the component is reading the urgent value directly somewhere inside.

Common Compilation/Runtime Mistakes

SymptomCauseFix
Input characters lag or revertControlled value set inside a transitionKeep the input urgent, defer the derived render
isPending never becomes trueNo state update inside the callbackMove the update inside startTransition
Pending flag flickersReading isPending in the same tick as the callIt is false until React re-renders
No improvement from the transitionExpensive work outside React state updatesDefer the render, not the calculation, or memoise
Deferred value identical to the valueObject recreated every renderPass a primitive or a stable object
Spinner flashes on every keystrokeSuspense boundary treated as urgentPut the boundary inside a transition
Async transition does nothing in React 18Pending scope ends at the first awaitManual pending state or React 19
List renders twice per keystrokeuseMemo keyed on the urgent valueKey it on the deferred value
startTransition called during renderInvalid call siteCall it from an event handler or effect

The useful mental model is a priority lane, not a delay knob. Nothing is throttled or debounced: the urgent lane always runs first, the background lane runs when the browser is idle and gives up as soon as something more important arrives. Reaching for setTimeout or a debounce when a transition would do trades correctness for latency, because a debounce delays the update the user asked for while a transition only delays the part they cannot see yet.

Try matching browser tools

All tools

Small utilities that fit React work — they run entirely in this browser tab, so nothing you paste leaves your device.

All React guides

More in React

All React guides

The guides filed next to this one in React, in library order.