How it works
startTransition is a flag around your callback, not a scheduler call. Simplified from React 19.3.1's ReactFiberHooks.js and ReactFiberWorkLoop.js (implementation details):
function startTransition(callback) {
setIsPending(true); // urgent: at least continuous-input priority
ReactSharedInternals.T = {}; // "a Transition is running"
try {
const result = callback(); // your setters run now
setIsPending(isThenable(result) ? afterActionSettles(result, false) : false);
} finally {
ReactSharedInternals.T = previous;
}
}
function requestUpdateLane(fiber) {
if (ReactSharedInternals.T !== null) return requestTransitionLane(); // one of 14 bits
return eventPriorityToLane(resolveUpdatePriority()); // click → sync lane
}
So isPending is ordinary state updated twice. The true update has input priority and commits right away: that's the first log line. The false update gets the Transition's lane, so it commits in the same render as your setTab. All Transition updates in one event share a lane, and the concurrent rendering question covers how Transition lanes render in time slices and get interrupted.
For an async callback, the false value is a thenable that resolves when the Action finishes; reading it suspends the render until then. React also reuses the same lane for every Transition started inside the running Action (its entangled action lane). That's why updates inside an Action wait for the whole Action.
Edge cases
State after await. By the time the code after an await runs, startTransition has returned and ReactSharedInternals.T is cleared: React can't follow async context. The docs say this will change once JavaScript has AsyncContext.
startTransition(async () => {
await delay(100);
setPage('unwrapped'); // not a Transition
await delay(100);
});
// → 0 ms: page=home isPending=true
// → 100 ms: page=unwrapped isPending=true
// → 200 ms: page=unwrapped isPending=false
startTransition(async () => {
await delay(100);
startTransition(() => setPage('wrapped'));
await delay(100);
});
// → 0 ms: page=unwrapped isPending=true
// → 200 ms: page=wrapped isPending=false
Chrome 156 and Firefox 159, development and production, times rounded to 10 ms (one Chrome run logged 210 ms). The wrapped update waited for the whole Action, so the user never saw the new page without the finished state.
- Controlled inputs. React restores a controlled input's DOM value to its current state after each change event. A listener on
document already saw "" after typing a; the value came back only with the commit.
- Errors. An error thrown in
useTransition's callback, or a rejected promise from an async one, is rethrown when the component renders, so the nearest error boundary shows it.
- Out of order. Actions in a Transition don't guarantee execution order, so a slow earlier response can overwrite a newer one. The docs point to
useActionState and <form> actions, which handle ordering.
Real-world scenario
A search box filtering a large list. The split that works keeps two states:
function handleChange(e) {
setText(e.target.value); // urgent: the input
startTransition(() => setQuery(e.target.value)); // non-urgent: the results
}
// Six keystrokes sent back to back; the results take 80 ms to render:
// → commit text=a query=
// … one commit per keystroke, query still empty …
// → commit text=abcdef query=
// → commit text=abcdef query=abcdef
That's Chrome 156, production build. The input committed on every keystroke; the results committed once, for the final query, because each newer keystroke interrupted the stale render. Firefox 159's slower automated typing let every query commit in between. Routers apply the same idea to navigation: wrap the URL state change in a Transition so the old page stays interactive and isPending drives a progress bar.
Trade-offs
A Transition buys responsiveness with extra renders: one for isPending, possibly several abandoned ones, and the final one, so total CPU goes up. The user sees stale content for longer, which is right for navigation and filtering but wrong for anything that must reflect input instantly. It needs code structure, too: the slow part must be split into components React can yield between, and the state must be yours to set. When those don't hold, useDeferredValue, memoization, or plain debouncing of network requests may fit better.