React Reference ยท Top-Level React APIs
React startTransition() function
Reference for React startTransition: mark state updates as non-urgent without a hook, use async actions, and know how it differs from useTransition.
startTransition runs a function and marks every state update made synchronously inside it as a transition. Transitions are non-urgent: React can interrupt them if something more important happens (such as typing), and it keeps showing the old UI instead of a Suspense fallback while the new UI is not ready.
It is the standalone version of useTransition. Use it where a hook is not available, for example in a library, a router or an event handler outside a component. The difference is that it gives you no isPending flag.
import { startTransition } from 'react'; startTransition(() => { setTab('posts'); });
Try it
Syntax
function startTransition(scope: () => void | Promise<void>): void;
| Name | Description |
|---|---|
scope |
A function that calls state setters (or other updates). Updates made synchronously while it runs are marked as a transition. It may be async (React 19). |
Returns: nothing (undefined).
Edge cases: the function runs immediately, not later. Errors thrown inside scope propagate to the nearest error boundary.
Usage notes
- No pending flag. If you need to show a spinner while the transition is running, use
useTransition, which returns[isPending, startTransition]. - Only synchronous updates are marked. In an async function, anything after the first
awaitis outside the transition. Wrap those later updates in anotherstartTransition, as in the second example. This limitation ofasynctransitions is expected to be lifted by future language features. - Cannot control text inputs. A controlled input's value must update urgently. Transitions are for the result of typing (a filtered list), not the input itself. Use
useDeferredValuewhen you only receive the value. - Updates from a transition can be interrupted and replaced by newer ones. Last write wins; React drops intermediate states.
- Suspense: inside a transition React does not hide already-visible content behind a fallback. New content stays hidden until it is ready.
- Do not use it to wait for data you did not start. It marks updates; it does not fetch or delay anything on its own.
- It is not a debounce. There is no timer: the update happens as soon as React has time.
- Server actions and forms: the
actionprop on forms anduseActionStaterun their work inside transitions for you.
Related
- lazy, memo, useState
- Lessons: Transitions, Async patterns, use and Suspense