Skip to content
Tutorials Center
My learning

Topics

Lesson 53 of 132 ยท Data and Async

Transitions, useTransition and useDeferredValue

Learn React transitions - urgent versus non-urgent updates, useTransition and isPending, async transitions in React 19, and useDeferredValue with live examples that count renders.

Not every state update deserves the same speed. When a user types a letter, the letter must appear now. When that letter also filters a list of ten thousand rows, the list can take a moment. If React treats both updates as equally urgent, a slow list makes the typing itself feel sticky.

React's answer is to let you label updates. An urgent update is a direct reaction to input: typing, clicking, pressing. A transition is an update that moves the UI to a new state but can wait, be interrupted, or be thrown away if something more important arrives. React renders transitions in the background and keeps the screen responsive. This lesson covers the three tools for it: startTransition, the useTransition hook with its isPending flag, and useDeferredValue. In React 19 transitions can also wrap async functions, which turns them into the foundation for form actions.

Why a slow render hurts

A render in React is plain JavaScript on the main thread. While your component tree renders, the browser cannot paint or react to the keyboard. If rendering a list takes 80 ms, every keystroke feels like it lags by 80 ms, because the input's new value cannot appear until that render has finished.

Transitions fix this without making anything faster. React starts rendering the non-urgent update, and if a new urgent update arrives (another keystroke), it pauses or abandons the background render, shows the urgent result first, and starts over with the latest data. Nothing is cancelled in your code; the abandoned render is simply never committed.

Transitions do not make rendering take less total work. They change when work happens and what may interrupt it. If a component is slow because it does too much, you still want to fix that (see memo and virtualization). Transitions are for work that is legitimately heavy.

Our examples need something slow to render. The helper below burns a little CPU per item. We never print timings, only render logs, so the results stay checkable.

startTransition: label a state update as non-urgent

Import startTransition from react and put the state update inside it:

JSX
import { startTransition } from 'react';

function handleChange(event) {
  setText(event.target.value);            // urgent: the input must stay in sync
  startTransition(() => {
    setListText(event.target.value);      // non-urgent: the slow list can lag
  });
}

Everything set inside the callback becomes a transition. The other setText call is outside, so it stays urgent. Use two pieces of state here because the input value must be urgent, while the thing that is expensive to render can wait.

useTransition and isPending

startTransition has no way to tell you that the transition is still running. The hook useTransition returns [isPending, startTransition] so you can show feedback: dim the old content, show a small spinner, disable a button.

A slow list behind a transition

Type a letter and study the console. On the first keystroke our run logged, in this order: App renders: text="a", isPending=true, then App renders: text="a", isPending=false, then SlowList renders for: "a". Read it carefully. The first App render is the urgent one: the input already shows a and the status line says Updating list..., but SlowList has not rendered, so the old list is still on screen (dimmed). The second App render is the transition render, which commits the new listText, and SlowList renders as part of it. The status line then returns to List is up to date. Typing a second letter produced the same three lines for "ab".

Two details deserve attention:

  • SlowList is wrapped in memo, so it only renders when its text prop changes. Without it, every urgent re-render of App would also re-render the slow list, and the transition would gain nothing.
  • isPending is true from the moment startTransition is called until the transition's render is committed. That is what lets you dim stale content instead of showing a blank gap.

What React does, step by step

When you call startTransition(() => setListText(value)):

  1. React marks the update with transition priority, below urgent updates.
  2. It first renders and commits the urgent update (setText, plus isPending flipping to true). The input shows the new character right away.
  3. It starts rendering the transition in the background. If a new urgent update arrives, it yields, handles the urgent update, then restarts the transition with the newest value.
  4. When the transition render finishes, React commits it and isPending becomes false.

A transition never shows a half-finished state. Either the old UI stays, or the complete new UI appears.

Transitions and Suspense

A transition has a second superpower: if the new render suspends (a component calls use(promise) on something not loaded), React does not replace the already visible content with a fallback. It keeps the old screen, with isPending true, until the data is ready. That is how you navigate between tabs without flashing a spinner every time.

Async transitions in React 19

Before React 19, startTransition required a synchronous callback. Now you can pass an async function. React keeps isPending true for the whole duration, until the promise settles, and lets you await server calls inside the transition. This is the engine behind <form action>.

An async transition keeps isPending true

Press Save. The button turns into Saving... and is disabled for about 300 ms, then the page shows Saved name: ada. The console order in our run was: render: isPending=false, action started, render: isPending=true, server answered: ada, and finally render: isPending=false, savedName=ada. The key observation is that isPending stayed true across the whole await, and the new savedName and the end of the pending state arrived in one render.

Note the inner startTransition after the await. React tracks the transition only for the synchronous part of the function, up to the first await. State updates that happen after an await lose that connection, so you must wrap them in startTransition again, or they are treated as ordinary urgent updates. We removed the inner wrapper and ran it again to see the difference: the log then contained render: isPending=true, savedName=ada followed by a separate render: isPending=false, savedName=ada. The new value showed up in its own urgent render while the transition was still marked pending, so the UI briefly showed new data and a "Saving..." button together. With the wrapper the two changes land in one commit. In React 19.3.1 the wrapper is the pattern to use.

Errors thrown inside an async transition are rethrown to the nearest error boundary. That means a failed save does not need its own try/catch just to be visible. If you want to handle the error yourself, catch it inside the function.

You cannot use a transition to control a text input's value. Controlled inputs must update synchronously, or characters get dropped or caret positions jump. Keep the input on the urgent path, as the first example does, and defer only what depends on it.

useDeferredValue: a lagging copy of a value

Sometimes you do not control the code that sets the state. A value arrives as a prop, and you only control how you use it. For this React offers useDeferredValue(value). It returns the value itself on the first render. When value changes, React first re-renders with the old value (instantly), then schedules a background render with the new one, which can be interrupted like a transition.

useDeferredValue keeps the old value first

Type a and read the console. Our run logged App renders: query="a", deferred="" first: the input is updated at once but Results still gets the old "", so it does not render (it is memoized and its prop did not change). Next came App renders: query="a", deferred="a" and only then Results renders for: "a". The sequence repeated for "ab".

Comparing query !== deferredQuery is the standard way to know the list is stale, the equivalent of isPending. Because Results is memoized and receives deferredQuery, it renders only when the deferred value catches up.

An initial value

useDeferredValue(value, initialValue) (added in React 19) controls what the very first render uses. Pass '' and the first render uses '' immediately, then a background render swaps in the real value. This is useful when the first render would be expensive, for example a large results page that should not block the page load.

useDeferredValue with an initial value

The page ends up showing Hello, Ada!, but the first log line is Greeting renders: name=Ada, deferredName=stranger: the very first render used the initial value, and a follow-up render (name=Ada, deferredName=Ada) swapped in the real one. Click the button and you get name=Grace, deferredName=Ada and then name=Grace, deferredName=Grace. After the first mount the initial value is not used again; later changes behave like the previous example.

useTransition or useDeferredValue?

Both create a lower-priority render. Choose by where the update comes from:

Situation Use
You own the setState call and can wrap it startTransition / useTransition (gives isPending)
The value comes from props or a parent you cannot change useDeferredValue
An update must await an async operation async useTransition
A navigation that may suspend should keep the old page a transition

Pitfalls professionals watch for

  • No memo, no benefit. If the slow child re-renders on every urgent update anyway, the lagging copy of the value saves nothing. Pair these tools with memo, or with a structure where the slow child only depends on the deferred value.
  • Transitions are not debouncing. A transition still renders every update eventually (unless superseded), and it does not delay network calls. To wait for the user to stop typing, see Async Patterns.
  • Do not defer what must be exact. A checkout total, a validation message that gates a button: show the true value, not a lagging one.
  • Timing is not a contract. Abandoned renders, intermediate logs and the number of background attempts differ between machines and React versions. Treat the order guarantees (urgent first, transition committed whole) as the contract, not the exact log.
  • Measure first. Open the profiler and confirm that rendering is really the bottleneck before reaching for these hooks. If the cost is in the DOM, in an effect, or in a network call, they will not help.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which update should stay urgent (outside startTransition)?

    A controlled input must update synchronously. Only the expensive consequences of the value, such as the filtered list, belong in the transition.
  2. 2. What does isPending tell you?

    isPending is true from the moment the transition starts until its render has been committed (or, for async transitions, until the promise settles).
  3. 3. In an async transition, why wrap setState after the await in startTransition again?

    React tracks the synchronous part of the function. After an await the context is gone, so mark the update as a transition explicitly.
  4. 4. When is useDeferredValue the better tool than useTransition?

    useDeferredValue lets the component that receives a value render a lagging copy of it, without control over where the value is set.
  5. 5. A slow child does not benefit from deferring its input. What is the most likely cause?

    If the slow child re-renders whenever its parent does, the urgent update already pays the full cost. Memoizing it makes it render only when the deferred value changes.

Summary

  • Urgent updates (typing, clicking) must show immediately; transitions are updates that may lag, be interrupted or be dropped.
  • startTransition(() => setState(...)) marks an update as a transition; useTransition also returns isPending for feedback.
  • React commits a transition only when its whole render is ready, and a transition that would suspend keeps the old content on screen.
  • Since React 19, a transition can be an async function; isPending stays true until it settles, and updates after an await need their own startTransition.
  • useDeferredValue(value, initialValue) gives a lagging copy of a value; compare it with the original to detect staleness.
  • Combine these tools with memo and measure first; they reschedule work, they do not remove it.

Next: Caching and Server State