Inside a TanStack Router Navigation

From application code, a navigation looks almost too simple:

await router.navigate({ to: '/account' })

That simplicity gets deceptive as soon as a few things overlap.

1. Hovering /account starts preloading it.
2. Clicking /account reuses the loading work that the hover started.
3. Before it finishes, the user clicks /settings, whose route loaders run in parallel.
4. One /settings loader errors while another redirects to /login.
5. The earlier /account work finishes and is cached, even though the user is no longer going there.
6. The router publishes /login, but its content suspends.
7. The framework eventually renders /login.

This is what the scenario looks like on a timeline. Don't worry about the labels yet, we'll unpack them as we go.

Why can /account keep loading after the user moves on, but no longer update the page? Why does the /settings error never appear? And why isn't publishing /login the end of the navigation?

A navigation looks like one asynchronous operation, but the router must decide four things independently: which loading work should continue, which navigation may publish, what the route attempt decided, and whether the framework rendered it.

That distinction came out of rewriting TanStack Router's loading system. We had dozens of bugs across preloading, redirects, caching, pending UI, SSR, and more. They looked unrelated, but many had the same root cause: the router compressed too many facts into too few variables. Cancellation, supersession, publication, and rendering were allowed to stand in for each other.¹

Application code still gets one navigate() call. Inside the router, separate lifetimes keep track of those four answers.²

Start With One Successful Navigation#

Before we return to all that overlap, it helps to focus on one ordinary navigation. There is no second click, no error, and no redirect here. The route simply loads slowly enough to show pending UI, then succeeds.

Each row follows a different part of the navigation, and the arrows between them are handoffs. Loaders can run while a pending timer races them. The framework can render pending UI while the private route branch keeps loading. We'll decode the internal labels just below.

The lane in the middle is a private, unpublished draft of the matched route branch. Following it across the diagram:

1. Route matching turns the destination URL into an ordered branch of route matches.
2. The navigation becomes the current transaction. This is what grants it permission to publish if it is still current when the work finishes.³
3. The private lane builds route context and runs beforeLoad from parent to child. Each child needs its parent's completed context, so this part is intentionally serial.
4. Eligible route loaders can then run in parallel. Each actual loader invocation is a loader flight.
5. If the loaders take longer than pendingMs, the router can publish pending UI. The framework handles that publication while the lane keeps working toward the final result.
6. Once the loader outcomes are ready, the lane selects the successful result.
7. This navigation is still current, so it publishes the final matches. The framework acknowledges that publication, and the navigation can finish.

Nothing goes wrong in this version. The transaction is never replaced, the loaders do not error or redirect, and both publications render successfully. Now change one assumption at a time:

Usually, all four answers arrive within a few milliseconds of each other, preserving the illusion of one asynchronous task, but it is also plenty of time for another event to change what should happen next.

When Navigations Overlap#

The opening scenario puts all four complications back together. Here is the whole thing at once, and then one section per complication.

Unlike the other diagrams, this one reads from top to bottom. Each column follows one owner: the current transaction, a private lane, a loader flight, or the framework render. The horizontal arrows pass work or results between them. This is only one possible interleaving; independent events, such as caching /account and publishing /login, could happen in either order.

A Replaced Navigation Can Leave Useful Work#

In the opening scenario, /account keeps loading after the user clicks away. Both the hover preload and the navigation need /account's data, but the loader should still run only once.

The preload and navigation still do their own matching, build their own context, and run their own beforeLoad. They share only the loader invocation and its outcome.

To decide when that shared invocation can be aborted, the router wraps it in a flight: a promise, an abort controller, and a lease count. Every consumer that needs the flight takes a lease.⁴

For /account, clicking /settings ends the navigation's claim. The preload still holds its own lease, so the count never reaches zero. The flight continues, settles, and its result enters the cache.

Losing permission to publish /account does not prove that its loader is useless. The transaction enforces whether /account may publish, and the flight's leases track whether the loader is still needed.

Only the Current Navigation May Publish#

Keeping a loader alive is separate from deciding whether its navigation may reach the page. In the simple example, one transaction stays current all the way through publication. In the complex scenario, /settings starts while the /account lane is still pending.

The current transaction is a single slot that holds which navigation is allowed to publish. When /settings takes the slot, /account loses that right. It does not matter whether some of /account's work is still useful; the lane can no longer update the page.

Discarding the navigation also releases its leases. Any pending flight with no other consumers may now abort. Our /account flight has the preload consumer, though, so it carries on.

if (router._tx !== tx) {
  finishPending(tx)
  discardLane(result)
  return
}

One Loader Result Is Not the Route Result#

In the successful navigation, every loader contributes to one successful result. The diagram below shows three outcomes: the root route succeeds, the parent layout loader rejects, and the child index loader throws redirect('/login').

Each settlement tells us what happened to one loader, but not yet what the whole route attempt should do. The outcomes go back to the private lane, which reduces them into one result.⁵

The error does not become the lane's result just because it settles first. Before choosing an ordinary failure, the lane waits for already-started loaders that could still redirect. It eventually chooses one result for the whole branch:

• A redirect starts a new navigation.
• A failure selects the error or not-found boundary that will render it.
• A success makes the complete lane eligible to publish.

It is tempting to say that the redirect "beats" the error, but that is not quite what happens. A redirect is control flow and not really a piece of UI. It discards the /settings lane and starts a new navigation to /login. Since that lane never publishes its final matches, the error never reaches the page.

Published Does Not Mean Rendered#

This section depends on the UI framework (React / Solid / Vue). We will use React for this explanation.

Both scenarios represent the end of a successful lane as two separate events: publish and acknowledge. Publishing means handing a route branch to the framework. It is a request to render, not proof that the framework committed that branch.⁷

React may still be busy with the previous tree. The new one can suspend on promises of its own (useSuspenseQuery, use(promise), lazy(() => import(...)), etc.), leaving the committed UI on screen. If another navigation publishes in the meantime, the earlier publication may never commit at all.

The diagram below shows that generic race.

To tell these cases apart, the router keeps a single receipt slot. A new publication acknowledges (ack) the previous receipt with false before installing its own. If React commits the new publication, the adapter acknowledges that receipt with true.⁸

ack:false does not mean the navigation failed. It means that exact publication was replaced before it committed. Either answer settles the receipt, but only ack:true proves that the framework rendered the publication.

Rendered here means that React committed the tree and ran its layout effects. It does not necessarily mean that the browser painted it.

Keeping Navigation Lifetimes Separate#

In the opening scenario, the user lands on /login, but four separate decisions produce that result. The /account loader continues because its preload still holds a lease. That same /account lane can no longer publish, because /settings took the transaction. The /settings lane sees an error, but its redirect starts a new /login navigation instead of producing UI. The framework then reports when /login actually commits.

navigate() can remain one promise because the router keeps these lifetimes separate. A lease says whether loader work is still needed. The current transaction says which navigation may publish. A private lane decides what one route attempt did. A receipt reports whether the framework rendered a publication.

await router.navigate({ to: '/account' })