React 18 Introduced the concept of "transitions" which allow you differentiate urgent from non-urgent UI updates. We won't try to explain transitions or the underlying "concurrent rendering" concept in this doc, but you can read up on those concepts here:
React 19 continued enhancing the async/concurrent landscape and introduces actions and support for using async functions in transitions. With the support for async transitions, a new `React.useOptimistic hook was introduced that allows you to surface state updates during a transition to show users instant feedback.
The introduction of transitions in React makes the story of how React Router manages your navigations and router state a bit more complicated. These are powerful APIs but they don't come without some nuance and added complexity. We aim to make React Router work seamlessly with the new React features, but in some cases there may exist some tension between the new React ways to do things and some patterns you are already using in your React Router apps (i.e., pending states, optimistic UI).
To ensure a smooth adoption story, we've introduced changes related to transitions behind an opt-in unstable_useTransitions flag so that you can upgrade in a non-breaking fashion.
Back in early 2023, Dan Abramov filed an issue for Remix v1 to use React.startTransition to "Remix router would be more Suspense-y". After a bit of clarification we implemented and shipped that in React Router 6.13.0 via behind a future.v7_startTransition flag. In v7, that became the default behavior and all router state updates are currently wrapped in React.startTransition.
This turns out to be potentially problematic behavior today for 2 reasons:
startTransition
React.useSyncExternalStore is incompatible with transitions (^1, ^2) so if you are using that in your application, you can run into tearing issues when combined with React.startTransitionflushSync option on navigations to use React.flushSync for the state updates instead, but that's not always the proper solutionstartTransition(() => Promise)) API as well as a new useOptimistic hook to surface updates during transitions
startTransition(() => navigate(path)) doesn't work as you might expect, because we are not using useOptimistic internally so router state updates don't surface during the navigation, which breaks hooks like useNavigationTo provide a solution to both of the above issues, we're introducing a new unstable_useTransitions prop for the router components that will let you opt-out of using startTransition for router state upodates (solving the first issue), or opt-into a more enhanced usage of startTransition + useOptimistic (solving the second issue). Because the current behavior is a bit incomplete with the new React 19 APIs, we plan to make the opt-in behavior the default in React Router v8, but we will likely retain the opt-out flag for use cases such as useSyncExternalStore.
unstable_useTransitions=falseIf your application is not "transition-friendly" due to the usage of useSyncExternalStore (or other reasons), then you can opt-out via the prop:
// Framework Mode (entry.client.tsx)
<HydratedRouter unstable_useTransitions={false} />
// Data Mode
<RouterProvider unstable_useTransitions={false} />
// Declarative Mode
<BrowserRouter unstable_useTransitions={false} />
This will stop the router from wrapping internal state updates in startTransition.
Suspense, use, startTransition, useOptimistic, <ViewTransition>, etc.
unstable_useTransitions=trueReact.useOptimistic
If you want to make your application play nicely with all of the new React 19 features that rely on concurrent mode and transitions, then you can opt-in via the new prop:
// Framework Mode (entry.client.tsx)
<HydratedRouter unstable_useTransitions />
// Data Mode
<RouterProvider unstable_useTransitions />
// Declarative Mode
<BrowserRouter unstable_useTransitions />
With this flag enabled:
React.startTransition (current behavior without the flag)<Link>/<Form> navigations will be wrapped in React.startTransition, using the promise returned by useNavigate/useSubmit so that the transition lasts for the duration of the navigation
useNavigate/useSubmit do not automatically wrap in React.startTransition, so you can opt-out of a transition-enabled navigation by using those directlyuseOptimistic
state.navigation for useNavigation()state.revalidation for useRevalidator()state.actionData for useActionData()state.fetchers for useFetcher() and useFetchers()state.location for useLocationstate.matches for useMatches(),state.loaderData for useLoaderData()state.errors for useRouteError()Enabling this flag means that you can now have fully-transition-enabled navigations that play nicely with any other ongoing transition-enabled aspects of your application.
The only APIs that are automatically wrapped in an async transition are <Link> and <Form>. For everything else, you need to wrap the operation in startTransition yourself.
// Automatically transition-enabled
<Link to="/path" />
<Form method="post" action="/path" />
// Manually transition-enabled
startTransition(() => navigate("/path"));
startTransition(() => submit(data, { method: 'post', action: "/path" }));
startTransition(() => fetcher.load("/path"));
startTransition(() => fetcher.submit(data, { method: "post", action: "/path" }));
// Not transition-enabled
navigate("/path");
submit(data, { method: 'post', action: "/path" });
fetcher.load("/path");
fetcher.submit(data, { method: "post", action: "/path" });
Important: You must always return or await the navigate promise inside startTransition so that the transition encompasses the full duration of the navigation. If you forget to return or await the promise, the transition will end prematurely and things won't work as expected.
// ✅ Returned promise
startTransition(() => navigate("/path"));
startTransition(() => {
setOptimistic(something);
return navigate("/path"));
});
// ✅ Awaited promise
startTransition(async () => {
setOptimistic(something);
await navigate("/path"));
});
// ❌ Non-returned promise
startTransition(() => {
setOptimistic(something);
navigate("/path"));
});
// ❌ Non-Awaited promise
startTransition(async () => {
setOptimistic(something);
navigate("/path"));
});
popstate navigationsDue to limitations in React itself, popstate navigations cannot be transition-enabled. Any state updates during a popstate event are automatically flushed synchronously so that the browser can properly restore scroll position and form data.
However, the browser can only do this if the navigation is instant. If React Router needs to run loaders on a back navigation, the browser will not be able to restore scroll position or form data (<ScrollRestoration> can handle scroll position for you).
It is therefore not recommended to wrap navigate(n) navigations in React.startTransition
unless you can manage your pending UI with local transition state (React.useTransition).
// ❌ This won't work correctly
startTransition(() => navigate(-1));
If you need programmatic back-navigations to be transition-friendly in your app, you can introduce a small hack to prevent React from detecting the event and letting the transition work as expected. React checks window.event to determine if the state updates are part of a popstate event, so if you clear that out in your own listener you can trick React into treating it like any other state update:
// Add this to the top of your browser entry file
window.addEventListener(
"popstate",
() => {
window.event = null;
},
{
capture: true,
},
);