Skip to content

React Transitions: Non-Urgent Updates with useTransition

useTransition marks updates as non-urgent and keeps React responsive during expensive or suspending renders. Plus useDeferredValue as the tool for downstream renders.

≈ 10 min readSoftwareFrontendReact

A React UI needs two priorities: one for what has to happen immediately and one for what can wait. React’s scheduler knows different priorities, but an ordinary state update is initially treated as a direct update. Only with a transition does the application explicitly mark the subsequent rendering work as non-blocking.

This becomes clearest at a point that already came up in the post on Suspense and the use Hook: the hard jump back to the fallback. The area is still showing real content, the state changes, the data is gone – and the spinner appears. That is exactly how a colleague’s question came up in a project: “The content is inside a Suspense boundary. When the state changes, the fallback kicks in. What are we supposed to do about that?” You tell React that this one update isn’t urgent. That is what useTransition is for.

Urgent or non-urgent – the only distinction that counts#

The dividing line runs between two kinds of updates. On one side are the urgent ones: I type a letter, and the character has to appear in the input field immediately. I check a checkbox, and it has to be checked immediately. Anything that should feel like a direct physical reaction is urgent. If React delays it by even 100 milliseconds, the app feels broken.

On the other side are the non-urgent updates: I switch tabs, I change the filter of a large list, I change the search query. The result of this action may take a moment. Nobody expects 10,000 newly filtered rows to appear in zero milliseconds. But what everyone does expect: that the UI doesn’t freeze in the meantime and doesn’t flicker pointlessly.

React can’t infer from the name of a state value which domain reaction may wait. With the concurrent features, which have been stably available since React 18 and the switch to createRoot, we get the tools to communicate this intent. useTransition is the most important of them.

The signature is deliberately simple#

import { useTransition } from 'react';

function TabContainer() {
  const [isPending, startTransition] = useTransition();
  const [tab, setTab] = useState('overview');

  function selectTab(nextTab) {
    startTransition(() => {
      setTab(nextTab);
    });
  }

  return (
    <>
      <TabButton active={tab === 'overview'} onClick={() => selectTab('overview')}>
        Overview
      </TabButton>
      <TabButton active={tab === 'reports'} onClick={() => selectTab('reports')}>
        Reports
      </TabButton>
      <section style={{ opacity: isPending ? 0.6 : 1 }}>
        <TabPanel tab={tab} />
      </section>
    </>
  );
}

The hook takes no parameters and returns a two-tuple: isPending, a Boolean, and startTransition, a function. Like any hook, you may only call it in a component or a custom hook.

The crucial part is in selectTab. The setTab call moves into the startTransition callback. With that, the component tells React: “This update is a transition.” If the new panel suspends inside a Suspense boundary that is already visible, React can leave the previous content in place instead of immediately replacing it with the fallback. Newly added Suspense boundaries, on the other hand, may still show their fallback. As long as the transition is running, isPending is true. In my example, that is exactly what the subtle graying out via opacity hangs on.

This is the concrete fulfillment of the Suspense promise: an update inside startTransition prevents content that is already visible from jumping back to the fallback.

What really happens in the background#

“React takes care of it” isn’t enough of an explanation, so here is the flow explicitly as a diagram. The important part is the branch at the end: a transition is interruptible.

flowchart TD
    A[User clicks tab] --> B[setTab runs in<br/>startTransition]
    B --> C[React renders new tab<br/>in the background]
    C --> D[Old UI stays visible<br/>isPending = true]
    D --> E{New data /<br/>render done?}
    E -->|yes| F[Switch to the new UI<br/>isPending = false]
    E -->|urgent update<br/>comes in| G[Background render is<br/>discarded and restarted]
    G --> C

The left path is the normal case: React renders in the background, keeps the old UI, shows isPending, and switches at the end. The right path is the reason the app stays responsive during expensive updates at all. If a more urgent update comes in during the background render – a keystroke, for example – React discards the half-finished work and starts over. You don’t have to wait until the expensive render is done before you can type again. This interruptibility is the real trick behind the word “concurrent.”

startTransition without a component#

Not every state change originates in a component. In routers and stores, the triggering logic often sits outside the component tree. For this case, there is the standalone import:

import { startTransition } from 'react';

function navigate(url) {
  startTransition(() => {
    setCurrentUrl(url);
  });
}

This variant works everywhere but has a price: it doesn’t provide isPending. If you want to show the loading state, you need the hook. If you only want to mark an update as non-urgent and get the pending state from somewhere else, the standalone import serves you well. I use it deliberately in router callbacks, where the navigation indicator lives somewhere else anyway.

By the way, since React 19, stable since December 2024, startTransition also accepts async functions; the new Actions and <form action> build on this internally. That is a topic of its own – all that matters here is that the transition mechanism itself is the foundation underneath.

The classic mistake: freezing the input field#

In code reviews, the same obvious mistake shows up at this point again and again. If a transition defuses expensive renders, why not simply wrap every update – including the search field’s?

// Do NOT do this
function onChange(e) {
  startTransition(() => {
    setText(e.target.value);
  });
}

The result is a sluggish, mushy input field. The reason: text in the input is an urgent update. It feels directly physical; every letter has to appear immediately. If you put it in a transition, React may delay and interrupt it – and it does. So controlled inputs stay urgent, and the text state is set as usual. What is expensive isn’t the typing but what follows from the text – the filtered list. And there is a separate tool for that.

useDeferredValue: when part of the display may lag behind#

useTransition marks state updates at the place that triggers them. useDeferredValue takes a different approach: the current value stays urgent and visible, while an expensive consumer may temporarily keep working with the previous version. That is useful for props, but just as much for local input state whose derived list should catch up more slowly.

import { useDeferredValue, useState } from 'react';

function SearchPage() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  const isStale = query !== deferredQuery;

  return (
    <>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      <div style={{ opacity: isStale ? 0.5 : 1 }}>
        <SlowList query={deferredQuery} />
      </div>
    </>
  );
}

Here, the input field stays urgent: setQuery runs without any transition, and every letter appears immediately. But the expensive SlowList doesn’t get query; it gets deferredQuery. React first keeps rendering with the old value – the list stays put for a moment – and then re-renders with the new value in the background. The comparison query !== deferredQuery tells me whether the list is currently stale, and I gray it out subtly in the meantime.

Since React 19, the signature takes an optional second argument: useDeferredValue(value, initialValue). Without initialValue, nothing is deferred on the very first render; if you provide it, the first pass renders with this initial value and pushes the real value into the background. For everyday use, the single-argument form is almost always enough.

One point that leads to misunderstandings again and again: useDeferredValue is not a debounce and not a throttle. There is no fixed delay, and it doesn’t prevent network requests. It is pure render prioritization. If you trigger a fetch on every keystroke, you have the same storm of fetches with useDeferredValue as before – only the rendering of the results is spread out. Debouncing the request remains a separate task.

The second classic: the lost context after await#

As soon as async functions come into play, almost everyone falls into the same trap:

// The transition context is lost after the await
startTransition(async () => {
  const data = await fetchPage(url);
  setPage(data); // no longer part of the transition
});

The setPage after the await no longer runs inside the transition. React tracks the transition context synchronously; after an await, the original call returned long ago. The fix is unspectacular: wrap the update after the await again.

startTransition(async () => {
  const data = await fetchPage(url);
  startTransition(() => {
    setPage(data);
  });
});

A related stumbling block: a set call that happens from inside a setTimeout isn’t marked as a transition either, even if the setTimeout is inside startTransition. The callback only runs later, outside the synchronous window. startTransition expects a synchronous update; anything pushed into a later tick falls out of the transition context.

Which tool when – the decision tree#

Whether useTransition or useDeferredValue applies depends on what may be delayed: the state transition itself or just a downstream part of the display.

flowchart TD
    A[Expensive update must not<br/>block interaction] --> B{May the transition<br/>itself wait?}
    B -->|yes| C[useTransition /<br/>startTransition]
    B -->|no, only the consumer| D[useDeferredValue]
    C --> E[Update is marked<br/>isPending available]
    D --> F[Current value applies immediately<br/>consumer catches up]
    E --> G[Both: old UI stays in place<br/>instead of fallback]
    F --> G

So the dividing line isn’t “which one is more modern” but simply the question of control. To condense it, here are the two tools side by side:

  • useTransition / startTransition: I control an update whose visible result may wait. I want to avoid the hard jump back to the fallback, and with the hook I also need isPending. Typical: a tab switch or a non-urgent navigation.
  • useDeferredValue: the current value must apply immediately, but an expensive consumer may still see the previous version for a moment. There is no pending flag, but there is the comparison value !== deferredValue to gray out stale displays. Typical: the large derived list under a fast input field.

What both have in common is that less urgent rendering work may take a back seat to a direct interaction. With a Suspense boundary that is already visible, the existing content can stay in place as a result. The difference lies in whether the triggering update or a value for downstream consumers is delayed; only useTransition provides isPending.

What I recommend in practice#

A few guardrails that have proven themselves in projects:

  • State that drives a controlled text field stays urgent and must not go into a transition. For other direct inputs, I check which part has to react immediately and which follow-up work can wait.
  • Navigation and tab switches can belong in startTransition if their target suspends or renders expensively. Routers may already handle this coordination themselves.
  • For expensive derived renders under a fast input, useDeferredValue is the tool, because the current input value should stay visible immediately and only the list catches up.
  • isPending and value !== deferredValue indicate that something is currently stale. I use them for subtle graying out instead of a full-page spinner. After all, the whole point is that the content doesn’t disappear.
  • The loss of context after await and in setTimeout is treacherous. If an update stubbornly behaves as urgent even though it is inside a transition, that is almost always the cause.

If you want to place the concurrent features in a broader context, you will find the bigger picture in my React overview from JSX to architecture. The key point for today stays narrow: React can’t know which domain reaction has to be visible immediately and which rendering work can wait. useTransition and useDeferredValue express this intent in different places. With expensive renders, this can keep the UI responsive; with Suspense content that is already visible, it lets you avoid an unnecessary jump back to the fallback.

Further reading#

Revised and translated from German with the help of AI.