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?
answer
- fetch, then patch the DOM
- needs blazor.web.js
- data-enhance-nav="false"
- data-permanent keeps an element
- enhancedload for page scripts
basics
~20 sEnhanced 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 sIn 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<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
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.
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.
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.
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