Routers and Transitions

[brophdawg11]

This is a follow up to the bluesky thread here. It spidered out into multiple little threads and areas of confusion/clarification so I'll try my best to present a coherent summary here and specifically call out areas of confusion along the way. Maybe we can thread each question below for easier sub-discussions?

React Router + Transitions

We've been working to get React Router compatible with the new async transitions and useOptimistic APIs in React 19.

Back in early version of Remix + React 18, we wrapped internal router state updates with startTransition at Dan's request, and I think at the time that worked fine for scenarios where destination pages suspended, etc.

Now with React 19, we're hoping to make entire navigations more transition-friendly. The React 18 blog post stated (emphasis mine):

However, long term, we expect the main way you’ll add concurrency to your app is by using a concurrent-enabled library or framework. In most cases, you won’t interact with concurrent APIs directly. For example, instead of developers calling startTransition whenever they navigate to a new screen, router libraries will automatically wrap navigations in startTransition.

In React Router v7 we began exposing the promises from our navigation hooks (useNavigate, useSubmit) and our non-navigation APIs (useFetcher().load, useFetcher().submit) in anticipation of React becoming more promise friendly and allowing us to wrap those async functions.

Fast forward to React 19 introducing async transitions:

In React 19, we’re adding support for using async functions in transitions to handle pending states, errors, forms, and optimistic updates automatically

And per the useTransition docs, the action parameter is:

A function that updates some state by calling one or more set functions
"transition friendly" is simply:

Therefore, we were under the impression that we could just do this to make our navigations "transition friendly":

startTransition(() => navigate('/'));

That works great! We had to then make sure that some of our router state could surface mid-navigation for things like useNavigation to show loading states, so we added some useOptimistic state inside the router to get that to surface. We've been putting this behind a new opt-in flag and it's been working great.

Here's a stackblitz using an experimental release of our new opt-in flag showing a transition-aware navigation with an entangled counter: https://stackblitz.com/edit/github-c3cj3ant-f9eriqwh

❓ Question 1 - In the thread, Ricky stated that "startTransition(() => Promise) is for posting mutations, not for getting data". Is that strictly true? And if so, is our approach incorrect?

FWIW nowhere in the useTransiton docs is the word "mutation" mentioned. Why can't a loading navigation be a transition? The Tabs example in the docs is just a loading transition, isn't it?

history.go/popstate navigations

During our testing, we found that everything worked as expected except navigate(-1). After a few days of scratching our heads we started the original thread and Ricky let us know about the internal popstate behavior (facebook/react#26025). This was incredibly surprising to discover - as we were convinced React wouldn't be messing with browser routing logic internally (especially without documentation).

The reasoning behind this feels idealistic and sort of fundamentally impossible in our eyes. In an ideal world, we'd have data available for back-navigations and they'd be fully synchronous, and therefore the browser could restore scroll position form inputs. But in reality, this feels fundamentally impossible.

❓ Question 2 - Is React's expectation that every history.go(n) has cached data? history.go(-10)? history.go(-100)?history.go(-1) after the cache has expired? Is the expectation that the router manages all of this so as not to have to call any user code?

React Router does not behave as a cache, and we leave that to the users loader functions. They can cache data there but it'll still be an await Promise.all(loadersToRun) on our end so it'll immediately be async. So the assumption being made inside React is incompatible with React Router apps using loaders.

Here's a stackblitz showing a transition-aware forward navigations working as expected, and a navigate(-1) wrapped in a transition not working as expected going back: https://stackblitz.com/edit/github-c3cj3ant-phzfymaj

We think that if a developer can call startTransition(() => navigate('/path')), then they should be able safely expect startTransition(() => navigate(-1)) to work the same way.

❓ Question 3 - At the very least - would React be open to making this behavior configurable by the user/router layer? Instead of something rigidly enforced by React?

There is an open issue around FALLBACK_THROTTLE_MS that has some relevant comments along the same vein:

I'm fine with defaults, as long as there are escape hatches. This should 100% be configurable, with the option to disable it entirely. It's not really React's responsibility to make this kind of choice for every app.

Since when has React become opinionated like this? Usually React always provided the building blocks and then let us choose how to use them. Why are we suddenly making decisions for devs and even library authors?

At the moment, we plan to document this as a React limitation and potentially even point out that it can be bypassed via:

window.addEventListener(
  'popstate',
  () => {
    window.event = null;
  },
  {
    capture: true,
  }
);

View Transitions

Also from the thread, it was mentioned React doesn't animate back navigations with ViewTransition. This also feels overly restrictive? To my knowledge, MPA view transitions work fine with back navigations? And the view transition support we have built into React Router today using startViewTransition also supports back navigation transitions without issue. We are planning to deprecate this in favor of <ViewTransition> eventually, but it feels like it could be a step back in UX for existing users if they lose back animations? As a user, if I clicked from a product grid to a product page and the image expanded into view, I would expect the reverse if I clicked back. It wouldn't very app-like otherwise (and I doubt my product/design team would accept "It can't be done" as a valid reason 😂).

❓ Question 4 - Does React have any intention of trying to make ViewTransition work on back navigations? This feels like more of an unfortunate consequence of the decisions made around popstate having to be synchronous, and not so much a technical limitation.

It's worth noting that applying the above window.event hack makes <ViewTransition> work fine on back navs in our testing in React Router.

[brophdawg11]

❓ Question 1 - In the thread, Ricky stated that "startTransition(() => Promise) is for posting mutations, not for getting data". Is that strictly true? And if so, is our approach incorrect?

[rickhanlonii]

In general yes - async transitions are for posting mutations, and sync transitions are for navigations (using GET in render with Suspense). I posted a longer explanation here, and I'll update the docs to explain this better.

But note that your demo was not using async transitions to load the (simulated) loader data, so that's not really the issue there.

[brophdawg11]

❓ Question 2 - Is React's expectation that every history.go(n) has cached data? history.go(-10)? history.go(-100)? history.go(-1) after the cache has expired? Is the expectation that the router manages all of this so as not to have to call any user code?

[rickhanlonii]

No, that's why for popstate we only attempt to synchronously render, and if we can't then we will go back to treating it as a transition. If the data is cached, then you get a fast, immediate back navigation which the browser can restore scroll, form, and video state for. If the data isn't cached, then it falls back to being treated like a normal transition navigation.

[brophdawg11]

❓ Question 3 - At the very least - would React be open to making this behavior configurable by the user/router layer? Instead of something rigidly enforced by React?

[rickhanlonii]

Maybe? But I think it's premature to ask for a feature before fullying understanding what's going on, and why things aren't working as expected. This behavior really shouldn't be observable by user or router code, so I think we should fix the bug and structure the router transitions correctly before jumping straight to configuration options. It's probably the case that this is the behavior you will want in the end, and it just looks like it isn't because of bugs.

[brophdawg11]

❓ Question 4 - Does React have any intention of trying to make ViewTransition work on back navigations? This feels like more of an unfortunate consequence of the decisions made around popstate having to be synchronous, and not so much a technical limitation.

[rickhanlonii]

No. The ViewTransition API is async, which means if back navigations are animated then we'd never support correct platform back navigations when you used View Transition. Instead, we attempt to do what the browser wants (reveal the last page immediately and synchronously) and if that fails, then we go back to a transition which can animate.

[rickhanlonii]

I think there may be some confusion here, because I think you may have interpreted what as said to mean "don't use transitions for navigations", which is not what I meant. For navigations, you should always do it in a sync transition:

// this is for the history API
// the navigation API is a bit different
function navigate(url) {
  startTransition(() => {
    setRouterState(() => {
      url,
      // other router state
    })
  });
}

Then, any data that you need to GET for the new route can be handled by suspense. This allows React to immediately navigate to the next page with suspense placeholders, and allow the browser to start downloading resources such and fonts and CSS that it will need in order to render. It's important not to delay the render for the next page here because it will slow down navigations and make your app feel slow.

This matches the recommendation in the docs for building a suspense enabled router.

Problems in the demo

The issue in the demo is that you're awaiting the loader in the middle of two transitions:

So you're effectively doing this:

function navigate(url) {
  // transition one
  startTransition(() => {
    addOptimisticState('loading');
    setRouterState(() => {
        url,
        // other router state
      })
  });
  
  // await outside transition
  await loaders(url);
  
  // transition two
  startTransition(() => {
    setRouterState(() => {
      url,
      // other router state
    })
  });
}

This isn't even using an async transition to GET the loader data and render the next route in the same UI transition, it's just scheduling two independent transitions. This is busted. You can see how it's busted if you try to add a useTransition or useOptimistic to your code, because it doesn't work as expected. The transition will immediately commit instead of waiting until the navigation completes.

Here's an example sandbox with how I would expect to be able to drop in a useOptimistic and see the optimistic state until the page navigation completes. The code is using useOptimistic so that every time you click a link, it shows that that link is loading:

<Link
  href="/a"
  navigateAction={async () => {
  setPendingRoute('/a');
  router.navigate('/a');
  }}
>
  Go to A {pendingRoute === '/a' && '...'}
</Link>

But in the sandbox, the '...' is never shown (it's actually rendered and flips back faster than you can see, which the console shows). This is because your await is in the middle of two transitions, instead of being inside an async transition which tells react to include the promise in the transition.

You can fix by using an async transition, like in this sandbox. And now you can see the optimistic state with '...' on the link, all the way through the new page rendering.

Importantly, this also even works for the back navigation! But we'll get back to that later.

Why transitions for GETs are bad

Even though this works with an async transition (which is in user land in the sandbox, but you could fix it in the router), using an async transition for this use case is bad UX. This makes the updates in the transition wait for the promise to finish before rendering any of the updates in the transition.

This means you can't start rendering or fetching anything else on the next page until after the loader finishes. Even if all your data is in the loader, you're still not able to parallelize fetching resources like fonts and stylesheets. You can do it in React Router if you want, but it just means alternative routers will be able to provide faster navigations.

There are exceptions of course, but that's why in general you should GET data in render with Suspense, and save async transitions for POSTing data to the server. We could call it out better in the docs, but the docs for async transitions include examples like (link):

function onSubmit(newQuantity) {
  startTransition(async function () {
    // mutation
    const savedQuantity = await updateQuantity(newQuantity);
    startTransition(() => {
      setQuantity(savedQuantity);
    });
  });
}

For mutations, it makes sense to not start rendering the next page by default until the mutation finishes, because you might fetch the data you're mutating before it's mutated. Though you can still pre-render that page with Activity to speed up the post-mutation navigation, ensuring that the loaders are refreshed after the mutation.

So:

• sync transitions: navigations, GET in render
• async transitions: mutations, POST in action

Why useOptimistic works in popstate

Above I mentioned that the useOptimistic works even for the popstate back navigation, which you can see in my sandbox. So why does it work there, and not in your original demo?

The key thing here is that we don't force updates in popstate to flush synchronously, we attempt to render them synchronously. If something suspends, or the transition can't otherwise complete (such as a pending action), then we give up and go back to the transition. It's like an optimistic sync render to see if everything is cached.

In the demo, this means the in the popstate, react attempts to synchronously render, and can't complete. So we go back to rendering it as a transition. This means the transition is still pending, and the optimistic state we set at the beginning of the transition is still used.

So in typically scenerios, the sync rendering of popstate really isn't observable to end users.

So why doesn't the original useOptimistic work?

In your demo, you're setting the optimistic state inside of the popstate event itself:

window.addEventListener('popstate', () => {
  startTransition(() => {
    setOptimistic(event.detail);
     setState(event.detail);
  });
});

This is a bit of an edge case because users would typically set the optimistic state before navigating, not in the middle of one. But the reason this doesn't work might just be a bug in React where we're dropping the optimistic update during the attempt to synchronously render the transition, and not restoring it when reverting back to the transition. I'll file a bug for this.

[brophdawg11]

The issue in the demo is that you're awaiting the loader in the middle of two transitions:

That’s not the right demo :). That’s the simplified repro we were using to nail down what was going on with popstate.

You asked for one using React Router directly which is provided above in https://stackblitz.com/edit/github-c3cj3ant-f9eriqwh.

In the RR demo, the navigate function itself (which returns a promise for the entire navigation) is wrapped in startTransition. And then internally, each independent state update (loading, idle) is it’s own transition.

So the react router flow ends up being something like this:

function navigate(url) {
  startTransition(async () => {
    startTransition(() => {
      addOptimisticState('loading');
      setRouterState(loading)
    });
  
    await loaders(url);
  
    startTransition(() => {
      setRouterState(idle)
    })
  });
}

Does that not follow the docs for async operations inside a transition?

Any async calls that are awaited in the action will be included in the Transition, but currently require wrapping any set functions after the await in an additional startTransition

[brophdawg11]

This means you can't start rendering or fetching anything else on the next page until after the loader finishes

This feels like a UX opinion, not a hard rule. I’ve personally never been a fan of hiding legitimate content in favor of skeletons during a navigation, What if the desired UX is a transparent overlay? In React Router we try hard not to force a UX on you. If you want an overlay, await in the loader. If you want skeletons, return promises and use Suspense/Await. But it doesn’t feel like our place to make the choice for you.

[rickhanlonii]

Do you have a code pointer to that in the RR router repo? I was searching for it but couldn't find it.

This feels like a UX opinion, not a hard rule. I’ve personally never been a fan of hiding legitimate content in favor of skeletons during a navigation, What if the desired UX is a transparent overlay?

Yeah, agreed, that's why by default if something on the new page suspends without a Suspense Boundary (i.e. suspends to the root) then we hold back the transition on the old page until the new page finishes (or we can complete with boundaries lower on the page). I.e. you pick the behavior of the page, on that page, not at the place you navigate. Different pages can define different behaviors.

it doesn’t feel like our place to make the choice for you.

I think the nuanced thing here is that if you await the loader in the transition, then you are making the choice for them. Awaiting the loader means you can't opt-in to skeletons with Suspense/Await. If you remove awaiting the loader, then you get the behavior of "If you want skeletons, return promises and use Suspense/Await." And if you don't then you can show an overlay, or inline spinner untl the new page is ready.

[rickhanlonii]

The other thing is that even if you do decide you want to hold back the transition on the previous page - you do still want to start rendering the next page in the background as soon as possible to warm the resources. So it's really not about the UX you want (you can choose to either get skeletons, or overlay the previous page). The bug is that if you await the loader, you won't start rendering the next page (either in the foreground or background) until after the loader finishes.

[rickhanlonii]

@brophdawg11 can you help me understand what the unexpected behavior is in your React Router sandbox?

This is what I'm seeing, which seems to be expected? It doesn't have the missing "loading" state like your demo repro did:

Screen.Recording.2025-11-19.at.9.23.14.PM.mov