skip to content

In a Blazor Web App, how does enhanced navigation work, what can it break, and how do you opt a link or page out of it?

level: seniorimportance: should knowfreq 36%

answer

  1. fetch, then patch the DOM
  2. needs blazor.web.js
  3. data-enhance-nav="false"
  4. data-permanent keeps an element
  5. enhancedload for page scripts

basics

~20 s

Enhanced navigation lets blazor.web.js intercept an internal link, fetch the page and patch the returned HTML into the current DOM instead of loading a new document. Turn it off per link or subtree with data-enhance-nav="false", or with forceLoad in code.

solid answer

~40 s

In a Blazor Web App without an interactive router, `blazor.web.js` intercepts clicks on internal links, sends a `fetch` marked as an enhanced request, and merges the response HTML into the existing DOM, keeping scroll position and the script runtime. A response from a non-Blazor endpoint is retried as a normal full page load. It can break page-specific `<script>` tags, which do not run again, and DOM changes made by JavaScript, which the patch can undo. Fixes are `data-permanent` on elements to keep, the `enhancedload` event to re-apply changes, and opting out: `data-enhance-nav="false"` on a link or any ancestor, `NavigateTo(..., forceLoad: true)` in code, or `Blazor.start({ ssr: { disableDomPreservation: true } })` for the whole app. Enhanced forms are separate: `Enhance` on `EditForm` or `data-enhance` on the form itself.

code

razor · 8 lines
razor
<ul data-enhance-nav="false">
    <li><a href="care-guides/print">Printable care guide (MVC)</a></li>
    <li><a href="exports/plants.csv">Download the catalog</a></li>
</ul>

<div id="cart-badge" data-permanent>
    @* updated by a script; the DOM merge leaves it alone *@
</div>

go deeper

for a junior

Recall that enhanced navigation fetches the next page and patches the DOM instead of a full reload, and that data-enhance-nav="false" opts a link out.

for a middle

Explain when it applies, how non-Blazor responses fall back to a full load, and the difference between data-enhance-nav for links and Enhance or data-enhance for forms.

for a senior

Show you can diagnose scripts that stop running, widgets reset by the DOM merge, and links that should be full loads, and fix them without disabling the feature.

for a principal

Weigh enhanced static pages against an interactive router for an app area, considering JavaScript-heavy pages, server load and how much client state must survive.

## What enhanced navigation is A classic server-rendered site performs a **full page load** for every link: the browser discards the document, requests new HTML, parses it, and re-runs every script. A Blazor Web App that renders pages with **static SSR** would pay that cost on every click. **Enhanced navigation** avoids it. The Blazor Web App script, `blazor.web.js`, intercepts the navigation, requests the page with `fetch`, and **patches** the returned HTML into the current DOM, changing only what differs. The address bar and history are updated as usual. It is on by default when all of these hold: - the page uses `blazor.web.js` (not `blazor.server.js` or `blazor.webassembly.js`); - it has not been disabled globally; - the destination is inside the app's base URI; - no `data-enhance-nav="false"` applies to the link. When the `Router` is interactive (a global render mode), links are handled by the interactive router instead and no HTML is fetched for a page change. ## How the request and response are recognised The `fetch` carries an `Accept` header marking it as an enhanced request (`text/html; blazor-enhanced-nav=on`). A Blazor endpoint answers with a header that allows the patch. If a **successful GET** response lacks it, for example a Razor Pages or MVC page in the same app, the script does not patch foreign HTML into the document: it retries the URL as a normal full page load. Error responses are patched in so the error page stays visible. Redirects to internal URLs are followed and the address bar shows the final URL; a redirect to another origin becomes a full navigation. ## What it can break | Symptom | Cause | Remedy | |---|---|---| | A chart or map script on one page runs only on a fresh load | page-specific `<script>` elements may not run again when content is patched | run page setup from an `enhancedload` listener (or a JS initializer) | | A widget's DOM changes vanish after a navigation | the patch makes the DOM match the server HTML again | mark the element `data-permanent` | | Code assumes navigation handlers always run | location-changing handlers run only for programmatic navigation from an interactive runtime, and `LocationChanged` is not guaranteed | do not rely on them for enhanced navigation | | A link to a file or non-Blazor page behaves oddly | the target is not meant to be patched | `data-enhance-nav="false"` or `forceLoad: true` | ## Opting out 1. **One link or a whole subtree:** `data-enhance-nav="false"` on the `<a>` or on any ancestor, such as a `<ul>`. The closest attribute wins, so an inner `data-enhance-nav` can switch it back on. 2. **Navigation in code:** `NavigationManager.NavigateTo(url, forceLoad: true)` always loads a new document; `forceLoad: false` uses enhanced navigation when it is available. 3. **The whole app:** start Blazor manually with `autostart="false"` and call `Blazor.start({ ssr: { disableDomPreservation: true } })`. ```javascript Blazor.start({ ssr: { disableDomPreservation: true } }); ``` ## Forms are a separate switch Enhanced **form** handling is opt-in, not opt-out. It is enabled with the `Enhance` parameter on `EditForm` or `data-enhance` on a `<form>`, and it is not inherited from an ancestor element. Enhanced posts work only against Blazor endpoints. Form handling in depth belongs to the forms topic; for navigation it is enough to know that `data-enhance-nav` does not affect forms. ## Keeping state and scripts alive - `data-permanent` on an element, such as the nursery's cart badge updated by a script, tells the DOM merge to leave it alone. - `Blazor.addEventListener('enhancedload', callback)` runs after every enhanced page update, including streaming updates, which is where page scripts re-attach. In 10.0.12 `enhancednavigationstart` and `enhancednavigationend` exist as well. - `NavigationManager.Refresh()` re-fetches the current page through enhanced navigation; `Refresh(forceReload: true)` reloads it. ## Diagnosing it in the browser In the network panel an enhanced navigation is a `fetch` request for the page URL, not a document request. If a link should be enhanced and shows a document request instead, check for an ancestor `data-enhance-nav="false"`, an absolute URL outside the base URI, a non-Blazor response, or a page still loading `blazor.server.js`.

  • Why does a link from a Blazor page to a Razor Pages page in the same app still work with enhanced navigation on?
    The script sends an enhanced `fetch`, and a successful GET response without Blazor's allow header is treated as a non-Blazor endpoint. Instead of patching that HTML into the document, the script retries the URL as a normal full page load.
  • Does enhanced navigation apply when the whole app uses InteractiveServer on the Routes component?
    Not for page changes. With an interactive `Router`, link clicks and `NavigateTo` are handled client-side by the router, which renders components over the circuit without fetching HTML. Enhanced navigation is the mechanism for statically rendered and per-page interactive apps.

Enhanced navigation is a stage crew that changes only the props that differ between scenes while the audience stays seated, instead of emptying the theatre and seating everyone again. A prop an actor added mid-scene, like a script's DOM change, is cleared away unless it is tagged to stay.

  • Enhanced navigation needs an interactive render mode on every page
  • Page-specific script tags reliably run again after every enhanced navigation
  • data-enhance-nav="false" also turns off enhanced form posts
  • A successful response from a Razor Pages page is patched into the Blazor DOM
  • Enhanced form handling is on by default for every EditForm