How a navigation works

The shape of a navigation

A click on a <BrouterLink>, a brouter.Navigate(...) call, or a Back/Forward press all enter the same pipeline. The decide phase hangs off Blazor's RegisterLocationChangingHandler, so a veto there means the browser URL is never written at all.

┌─────────────── DECIDE (URL has not moved yet) ───────────────┐
  click / Navigate  │  lazy assemblies → leave guards → OnNavigating →     │
  Back / Forward  ──▶  match → enter guards → RedirectTo                   │
                    └──────────────────────────────┬───────────────────────────────┘
                                       │ approved  →  the URL commits
                    ┌──────────────────────────────┴───────────────────────────────┐
                    │  COMMIT: loaders → render → OnMatch / OnNavigated →   │
                    │          scroll & focus → lifecycle arrivals          │
                    └──────────────────────────────────────────────────────────────┘

  cancelled or redirected anywhere in DECIDE
      → the navigation is prevented; the address bar never moved

The seven steps, in order

Each step runs to completion (awaited) before the next begins. Any step that cancels or redirects ends the phase immediately - later steps never run.

Note the direction change between steps 2 and 5: departures run leaf → root (the code closest to the state at risk gets the first veto) and arrivals run root → leaf (a parent authorizes before its children are considered). The same inversion applies to loaders and lifecycle callbacks in phase 2.

Why "preventive" matters

Most SPA routers let the URL change and then undo it if something objects. That produces a visible address-bar flicker, a history entry that has to be popped back off, and a Back button that no longer means what the user thinks. Because Brouter decides first, cancelling is a non-event: no flicker, no history to repair, and the page the user is on never unmounts. It is also what makes a genuine "you have unsaved changes" prompt possible - the dialog can hold the navigation open and the answer still decides the outcome.

From approved URL to rendered page

The commit phase re-selects the same winner (matching is a pure function of the URL and the route set, so it can't disagree with phase 1) and then does the work that produces pixels. Nothing here can veto the navigation - by this point the decision has been made.

Cancel, redirect, throw

Guards, locks and the global hook all steer the navigation through the same context object. The three exits behave differently on purpose:

Exceptions in the commit phase - a loader that throws, a failing lifecycle callback - take a different route: they surface in the nearest error boundary (bubbling leaf → root, with the router-level ErrorContent as the last resort) so the rest of the app keeps rendering, and RetryAsync() can re-run the pipeline in place.

Supersession: the newest navigation wins

Users click faster than networks respond. Every await point in the pipeline is version-checked, so when a second navigation starts while the first is still awaiting a slow guard or loader, the older one stops where it is: its remaining steps are skipped, its CancellationToken fires (so your own HttpClient calls abort too), and it never renders, scrolls or fires OnNavigated on behalf of a page the user already left. NavigateAsync reports that as Superseded.

This is why long-running guards and loaders should thread ctx.CancellationToken through their async calls - it is the router telling you the answer is no longer wanted. The same token is what lets a lock's confirmation dialog dismiss itself when the pending navigation it was asking about gets replaced.

Navigation vs reload vs revalidation vs preload

Not everything that runs a loader is a navigation. Three operations deliberately run a subset of the pipeline, and knowing which subset explains their guarantees.

Revalidation is "refresh what's on screen after a mutation": same URL, no guards, no flash of pending UI, and it's a no-op if nothing in the current chain has a loader. Reload is the heavy one next to it - the current chain's components are disposed and recreated, so it is what you reach for when the page's derived state is stale and not just its data (switching tenant, impersonating a user). It runs the matching half of the pipeline because its chain is being built from nothing, which is why enter guards and RedirectTo get a say and leave guards do not. Preloading is speculative - it must never have side effects, which is exactly why guards are skipped and failures are swallowed. Branch on ctx.IsReload / ctx.IsRevalidation / ctx.IsPreload when a loader should behave differently (skipping a telemetry ping on a preload, say).

A reload requested while a navigation is in flight - from the moment that navigation starts, guards included - does nothing: that navigation is already rebuilding the page the user is heading to. Neither does a reload with nothing committed (a not-found fallback or an error boundary on screen): there is no chain to rebuild. The lighter ClearKeepAlive(includeActive: true) throws the instances away without running any of this pipeline at all - see lifecycle & keep-alive.

The last case is the shortest: Navigate(url, forceLoad: true) skips the pipeline entirely. The browser loads a new document, so the SPA process that would have run the guards is replaced outright - which is also why NavigateAsync doesn't offer it, as there would be nothing left alive to resolve the task.

Where to go from here

• Guards & navigation locks - steps 2, 3 and 5 in depth.
• Data loading - step 9, plus the cache that lets it be skipped.
• Lifecycle & keep-alive - step 13 and what retention changes about it.
• Scroll & focus - step 12's precedence rules.
• API reference - every parameter, option and context type named above.