Skip to content

Split the Routing & Navigation article #36145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Split the Routing & Navigation article #36145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
428f8c9
Split the Routing & Navigation article
guardrex Sep 23, 2025
5911969
Updates
guardrex Sep 23, 2025
fc969ab
Updates
guardrex Sep 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions aspnetcore/blazor/call-web-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -626,14 +626,14 @@ When prerendering, components render twice: first statically, then interactively
You can address this by flowing prerendered state using the Persistent Component State API, which the `BlazorWebAppCallWebApi` and `BlazorWebAppCallWebApi_Weather` [sample apps](#sample-apps) demonstrate. When the component renders interactively, it can render the same way using the same state. For more information, see the following resources:

* <xref:blazor/state-management/prerendered-state-persistence>
* <xref:blazor/fundamentals/routing#enhanced-navigation-and-form-handling>
* <xref:blazor/fundamentals/navigation#enhanced-navigation-and-form-handling>

:::moniker-end

:::moniker range="< aspnetcore-10.0"

> [!NOTE]
> The Persistent Component State API only supports enhanced navigation in .NET 10 or later. For apps that target .NET 8 or .NET 9, you can disable enhanced navigation on links to the page with the `data-enhance-nav` attribute set to `false`. For more information, see <xref:blazor/fundamentals/routing#enhanced-navigation-and-form-handling>.
> The Persistent Component State API only supports enhanced navigation in .NET 10 or later. For apps that target .NET 8 or .NET 9, you can disable enhanced navigation on links to the page with the `data-enhance-nav` attribute set to `false`. For more information, see <xref:blazor/fundamentals/navigation#enhanced-navigation-and-form-handling>.

:::moniker-end

Expand Down
18 changes: 9 additions & 9 deletions aspnetcore/blazor/components/built-in-components.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,8 @@ The following built-in Razor components are provided by the Blazor framework. Fo
* [`InputTextArea`](xref:blazor/forms/input-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#create-a-layout-component)
* [`LayoutView`](xref:blazor/components/layouts#apply-a-layout-to-arbitrary-content-layoutview-component)
* [`NavigationLock`](xref:blazor/fundamentals/routing#handleprevent-location-changes)
* [`NavLink`](xref:blazor/fundamentals/routing#navlink-component)
* [`NavigationLock`](xref:blazor/fundamentals/navigation#handleprevent-location-changes)
* [`NavLink`](xref:blazor/fundamentals/navigation#navlink-component)
* [`PageTitle`](xref:blazor/components/control-head-content)
* [`OwningComponentBase`](xref:fundamentals/dependency-injection#utility-base-component-classes-to-manage-a-di-scope)
* [`Paginator`](xref:blazor/components/quickgrid#page-items-with-a-paginator-component)
Expand Down Expand Up @@ -79,8 +79,8 @@ The following built-in Razor components are provided by the Blazor framework. Fo
* [`InputTextArea`](xref:blazor/forms/input-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#create-a-layout-component)
* [`LayoutView`](xref:blazor/components/layouts#apply-a-layout-to-arbitrary-content-layoutview-component)
* [`NavigationLock`](xref:blazor/fundamentals/routing#handleprevent-location-changes)
* [`NavLink`](xref:blazor/fundamentals/routing#navlink-component)
* [`NavigationLock`](xref:blazor/fundamentals/navigation#handleprevent-location-changes)
* [`NavLink`](xref:blazor/fundamentals/navigation#navlink-component)
* [`PageTitle`](xref:blazor/components/control-head-content)
* [`OwningComponentBase`](xref:fundamentals/dependency-injection#utility-base-component-classes-to-manage-a-di-scope)
* [`Paginator`](xref:blazor/components/quickgrid#page-items-with-a-paginator-component)
Expand Down Expand Up @@ -117,8 +117,8 @@ The following built-in Razor components are provided by the Blazor framework. Fo
* [`InputTextArea`](xref:blazor/forms/input-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#create-a-layout-component)
* [`LayoutView`](xref:blazor/components/layouts#apply-a-layout-to-arbitrary-content-layoutview-component)
* [`NavigationLock`](xref:blazor/fundamentals/routing#handleprevent-location-changes)
* [`NavLink`](xref:blazor/fundamentals/routing#navlink-component)
* [`NavigationLock`](xref:blazor/fundamentals/navigation#handleprevent-location-changes)
* [`NavLink`](xref:blazor/fundamentals/navigation#navlink-component)
* [`OwningComponentBase`](xref:fundamentals/dependency-injection#utility-base-component-classes-to-manage-a-di-scope)
* [`PageTitle`](xref:blazor/components/control-head-content)
* [`Router`](xref:blazor/fundamentals/routing#route-templates)
Expand Down Expand Up @@ -151,7 +151,7 @@ The following built-in Razor components are provided by the Blazor framework. Fo
* [`InputTextArea`](xref:blazor/forms/input-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#create-a-layout-component)
* [`LayoutView`](xref:blazor/components/layouts#apply-a-layout-to-arbitrary-content-layoutview-component)
* [`NavLink`](xref:blazor/fundamentals/routing#navlink-component)
* [`NavLink`](xref:blazor/fundamentals/navigation#navlink-component)
* [`OwningComponentBase`](xref:fundamentals/dependency-injection#utility-base-component-classes-to-manage-a-di-scope)
* [`PageTitle`](xref:blazor/components/control-head-content)
* [`Router`](xref:blazor/fundamentals/routing#route-templates)
Expand Down Expand Up @@ -179,7 +179,7 @@ The following built-in Razor components are provided by the Blazor framework. Fo
* [`InputTextArea`](xref:blazor/forms/input-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#create-a-layout-component)
* [`LayoutView`](xref:blazor/components/layouts#apply-a-layout-to-arbitrary-content-layoutview-component)
* [`NavLink`](xref:blazor/fundamentals/routing#navlink-component)
* [`NavLink`](xref:blazor/fundamentals/navigation#navlink-component)
* [`OwningComponentBase`](xref:fundamentals/dependency-injection#utility-base-component-classes-to-manage-a-di-scope)
* [`Router`](xref:blazor/fundamentals/routing#route-templates)
* [`RouteView`](xref:blazor/fundamentals/routing#route-templates)
Expand All @@ -205,7 +205,7 @@ The following built-in Razor components are provided by the Blazor framework. Fo
* [`InputTextArea`](xref:blazor/forms/input-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#create-a-layout-component)
* [`LayoutView`](xref:blazor/components/layouts#apply-a-layout-to-arbitrary-content-layoutview-component)
* [`NavLink`](xref:blazor/fundamentals/routing#navlink-component)
* [`NavLink`](xref:blazor/fundamentals/navigation#navlink-component)
* [`OwningComponentBase`](xref:fundamentals/dependency-injection#utility-base-component-classes-to-manage-a-di-scope)
* [`Router`](xref:blazor/fundamentals/routing#route-templates)
* [`RouteView`](xref:blazor/fundamentals/routing#route-templates)
Expand Down
50 changes: 1 addition & 49 deletions aspnetcore/blazor/components/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: Learn how to create and use Razor components in Blazor apps, includ
monikerRange: '>= aspnetcore-3.1'
ms.author: wpickett
ms.custom: mvc
ms.date: 11/12/2024
ms.date: 09/23/2025
uid: blazor/components/index
---
# ASP.NET Core Razor components
Expand Down Expand Up @@ -528,54 +528,6 @@ In the following example, the `BlazorRocksBase1` base class derives from <xref:M

:::moniker-end

### Routing

Routing in Blazor is achieved by providing a route template to each accessible component in the app with an [`@page`][9] directive. When a Razor file with an [`@page`][9] directive is compiled, the generated class is given a <xref:Microsoft.AspNetCore.Mvc.RouteAttribute> specifying the route template. At runtime, the router searches for component classes with a <xref:Microsoft.AspNetCore.Mvc.RouteAttribute> and renders whichever component has a route template that matches the requested URL.

The following `HelloWorld` component uses a route template of `/hello-world`, and the rendered webpage for the component is reached at the relative URL `/hello-world`.

`HelloWorld.razor`:

:::moniker range=">= aspnetcore-9.0"

:::code language="razor" source="~/../blazor-samples/9.0/BlazorSample_BlazorWebApp/Components/Pages/HelloWorld.razor":::

:::moniker-end

:::moniker range=">= aspnetcore-8.0 < aspnetcore-9.0"

:::code language="razor" source="~/../blazor-samples/8.0/BlazorSample_BlazorWebApp/Components/Pages/HelloWorld.razor":::

:::moniker-end

:::moniker range=">= aspnetcore-7.0 < aspnetcore-8.0"

:::code language="razor" source="~/../blazor-samples/7.0/BlazorSample_WebAssembly/Pages/index/HelloWorld.razor":::

:::moniker-end

:::moniker range=">= aspnetcore-6.0 < aspnetcore-7.0"

:::code language="razor" source="~/../blazor-samples/6.0/BlazorSample_WebAssembly/Pages/index/HelloWorld.razor":::

:::moniker-end

:::moniker range=">= aspnetcore-5.0 < aspnetcore-6.0"

:::code language="razor" source="~/../blazor-samples/5.0/BlazorSample_WebAssembly/Pages/index/HelloWorld.razor":::

:::moniker-end

:::moniker range="< aspnetcore-5.0"

:::code language="razor" source="~/../blazor-samples/3.1/BlazorSample_WebAssembly/Pages/index/HelloWorld.razor":::

:::moniker-end

The preceding component loads in the browser at `/hello-world` regardless of whether or not you add the component to the app's UI navigation. Optionally, components can be added to the `NavMenu` component so that a link to the component appears in the app's UI-based navigation.

For the preceding `HelloWorld` component, you can add a `NavLink` component to the `NavMenu` component. For more information, including descriptions of the `NavLink` and `NavMenu` components, see <xref:blazor/fundamentals/routing>.

### Markup

A component's UI is defined using [Razor syntax](xref:mvc/views/razor), which consists of Razor markup, C#, and HTML. When an app is compiled, the HTML markup and C# rendering logic are converted into a component class. The name of the generated class matches the name of the file.
Expand Down
2 changes: 1 addition & 1 deletion aspnetcore/blazor/components/render-modes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -357,7 +357,7 @@ During static SSR, Razor component page requests are processed by server-side AS

If the app exhibits root-level interactivity, server-side ASP.NET Core request processing isn't involved after the initial static SSR, which means that the preceding Blazor features work as expected.

[Enhanced navigation](xref:blazor/fundamentals/routing#enhanced-navigation-and-form-handling) with static SSR requires special attention when loading JavaScript. For more information, see <xref:blazor/js-interop/ssr>.
[Enhanced navigation](xref:blazor/fundamentals/navigation#enhanced-navigation-and-form-handling) with static SSR requires special attention when loading JavaScript. For more information, see <xref:blazor/js-interop/ssr>.

## Interactive server-side rendering (interactive SSR)

Expand Down
4 changes: 2 additions & 2 deletions aspnetcore/blazor/components/rendering.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,9 +57,9 @@ To stream content updates when using static server-side rendering (static SSR) o

:::moniker range=">= aspnetcore-10.0"

If [enhanced navigation](xref:blazor/fundamentals/routing#enhanced-navigation-and-form-handling) is active, streaming rendering renders [Not Found responses](xref:blazor/fundamentals/routing#not-found-responses) without reloading the page. When enhanced navigation is blocked, the framework redirects to Not Found content with a page refresh.
If [enhanced navigation](xref:blazor/fundamentals/navigation#enhanced-navigation-and-form-handling) is active, streaming rendering renders [Not Found responses](xref:blazor/fundamentals/navigation#not-found-responses) without reloading the page. When enhanced navigation is blocked, the framework redirects to Not Found content with a page refresh.

Streaming rendering can only render components that have a route, such as a [`NotFoundPage` assignment](xref:blazor/fundamentals/routing#not-found-responses) (`NotFoundPage="..."`) or a [Status Code Pages Re-execution Middleware page assignment](xref:fundamentals/error-handling#usestatuscodepageswithreexecute) (<xref:Microsoft.AspNetCore.Builder.StatusCodePagesExtensions.UseStatusCodePagesWithReExecute%2A>). The Not Found render fragment (`<NotFound>...</NotFound>`) and the `DefaultNotFound` 404 content ("`Not found`" plain text) don't have routes, so they can't be used during streaming rendering.
Streaming rendering can only render components that have a route, such as a [`NotFoundPage` assignment](xref:blazor/fundamentals/navigation#not-found-responses) (`NotFoundPage="..."`) or a [Status Code Pages Re-execution Middleware page assignment](xref:fundamentals/error-handling#usestatuscodepageswithreexecute) (<xref:Microsoft.AspNetCore.Builder.StatusCodePagesExtensions.UseStatusCodePagesWithReExecute%2A>). The Not Found render fragment (`<NotFound>...</NotFound>`) and the `DefaultNotFound` 404 content ("`Not found`" plain text) don't have routes, so they can't be used during streaming rendering.

Streaming `NavigationManager.NotFound` content rendering uses (in order):

Expand Down
8 changes: 4 additions & 4 deletions aspnetcore/blazor/forms/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ In the preceding `StarshipPlainForm` component:
> [!IMPORTANT]
> Always use the [`@formname`](xref:mvc/views/razor#formname) directive attribute with a unique form name.

Blazor enhances page navigation and form handling by intercepting the request in order to apply the response to the existing DOM, preserving as much of the rendered form as possible. The enhancement avoids the need to fully load the page and provides a much smoother user experience, similar to a single-page app (SPA), although the component is rendered on the server. For more information, see <xref:blazor/fundamentals/routing#enhanced-navigation-and-form-handling>.
Blazor enhances page navigation and form handling by intercepting the request in order to apply the response to the existing DOM, preserving as much of the rendered form as possible. The enhancement avoids the need to fully load the page and provides a much smoother user experience, similar to a single-page app (SPA), although the component is rendered on the server. For more information, see <xref:blazor/fundamentals/navigation#enhanced-navigation-and-form-handling>.

<!-- UPDATE 11.0 - Check the PU issue (backlogged as of 2/27/25 -->

Expand Down Expand Up @@ -124,7 +124,7 @@ In the preceding `Starship1` component:
> [!IMPORTANT]
> Always use the <xref:Microsoft.AspNetCore.Components.Forms.EditForm.FormName> property with a unique form name.

Blazor enhances page navigation and form handling for <xref:Microsoft.AspNetCore.Components.Forms.EditForm> components. For more information, see <xref:blazor/fundamentals/routing#enhanced-navigation-and-form-handling>.
Blazor enhances page navigation and form handling for <xref:Microsoft.AspNetCore.Components.Forms.EditForm> components. For more information, see <xref:blazor/fundamentals/navigation#enhanced-navigation-and-form-handling>.

<!-- UPDATE 11.0 - Check the PU issue (backlogged as of 2/27/25 -->

Expand Down Expand Up @@ -337,7 +337,7 @@ To mitigate overposting, we recommend using a separate view model/data transfer

## Enhanced form handling

[Enhance navigation](xref:blazor/fundamentals/routing#enhanced-navigation-and-form-handling) for form POST requests with the <xref:Microsoft.AspNetCore.Components.Forms.EditForm.Enhance%2A> parameter for <xref:Microsoft.AspNetCore.Components.Forms.EditForm> forms or the `data-enhance` attribute for HTML forms (`<form>`):
[Enhance navigation](xref:blazor/fundamentals/navigation#enhanced-navigation-and-form-handling) for form POST requests with the <xref:Microsoft.AspNetCore.Components.Forms.EditForm.Enhance%2A> parameter for <xref:Microsoft.AspNetCore.Components.Forms.EditForm> forms or the `data-enhance` attribute for HTML forms (`<form>`):

```razor
<EditForm ... Enhance ...>
Expand Down Expand Up @@ -380,7 +380,7 @@ In the following example, the content of the `<div>` element is updated dynamica

To disable enhanced navigation and form handling globally, see <xref:blazor/fundamentals/startup#enhanced-navigation-and-form-handling>.

For guidance on using the `enhancedload` event to listen for enhanced page updates, see <xref:blazor/fundamentals/routing#enhanced-navigation-and-form-handling>.
For guidance on using the `enhancedload` event to listen for enhanced page updates, see <xref:blazor/fundamentals/navigation#enhanced-navigation-and-form-handling>.

:::moniker-end

Expand Down
2 changes: 1 addition & 1 deletion aspnetcore/blazor/fundamentals/dependency-injection.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ The services shown in the following table are commonly used in Blazor apps.
| ------- | -------- | ----------- |
| <xref:System.Net.Http.HttpClient> | Scoped | <p>Provides methods for sending HTTP requests and receiving HTTP responses from a resource identified by a URI.</p><p>Client-side, an instance of <xref:System.Net.Http.HttpClient> is registered by the app in the `Program` file and uses the browser for handling the HTTP traffic in the background.</p><p>Server-side, an <xref:System.Net.Http.HttpClient> isn't configured as a service by default. In server-side code, provide an <xref:System.Net.Http.HttpClient>.</p><p>For more information, see <xref:blazor/call-web-api>.</p><p>An <xref:System.Net.Http.HttpClient> is registered as a scoped service, not singleton. For more information, see the [Service lifetime](#service-lifetime) section.</p> |
| <xref:Microsoft.JSInterop.IJSRuntime> | <p>**Client-side**: Singleton</p><p>**Server-side**: Scoped</p><p>The Blazor framework registers <xref:Microsoft.JSInterop.IJSRuntime> in the app's service container.</p> | <p>Represents an instance of a JavaScript runtime where JavaScript calls are dispatched. For more information, see <xref:blazor/js-interop/call-javascript-from-dotnet>.</p><p>When seeking to inject the service into a singleton service on the server, take either of the following approaches:</p><ul><li>Change the service registration to scoped to match <xref:Microsoft.JSInterop.IJSRuntime>'s registration, which is appropriate if the service deals with user-specific state.</li><li>Pass the <xref:Microsoft.JSInterop.IJSRuntime> into the singleton service's implementation as an argument of its method calls instead of injecting it into the singleton.</li></ul> |
| <xref:Microsoft.AspNetCore.Components.NavigationManager> | <p>**Client-side**: Singleton</p><p>**Server-side**: Scoped</p><p>The Blazor framework registers <xref:Microsoft.AspNetCore.Components.NavigationManager> in the app's service container.</p> | Contains helpers for working with URIs and navigation state. For more information, see [URI and navigation state helpers](xref:blazor/fundamentals/routing#uri-and-navigation-state-helpers). |
| <xref:Microsoft.AspNetCore.Components.NavigationManager> | <p>**Client-side**: Singleton</p><p>**Server-side**: Scoped</p><p>The Blazor framework registers <xref:Microsoft.AspNetCore.Components.NavigationManager> in the app's service container.</p> | Contains helpers for working with URIs and navigation state. For more information, see [URI and navigation state helpers](xref:blazor/fundamentals/navigation#uri-and-navigation-state-helpers). |

Additional services registered by the Blazor framework are described in the documentation where they're used to describe Blazor features, such as configuration and logging.

Expand Down
Loading