[11.0 P1] Blazor Web can use BasePath component instead of <base href=""> (#36428)

ilonatommy · web-flow · commit 80a945ee6ca0 · 2026-02-10T12:11:20.000-05:00
diff --git a/aspnetcore/blazor/host-and-deploy/app-base-path.md b/aspnetcore/blazor/host-and-deploy/app-base-path.md
@@ -60,19 +60,23 @@ For the sources of links that pertain to Blazor in ASP.NET Core apps:
 
 If you're rendering a Blazor app from different documents (for example, `/Admin/B/C/` and `/Admin/D/E/`), you must take the app base path into account, or the base path is different when the app renders in each document and the resources are fetched from the wrong URLs.
 
-There are two approaches to deal with the challenge of resolving relative links correctly:
+Choose one of the following strategies to keep relative links resolving correctly:
 
-* Map the resources dynamically using the document they were rendered on as the root.
-* Set a consistent base path for the document and map the resources under that base path.
+* Map resources dynamically using the document they were rendered on as the root. This requires custom routing logic (for example, <xref:Microsoft.AspNetCore.Routing.IDynamicEndpointMetadata> or a <xref:Microsoft.AspNetCore.Routing.MatcherPolicy>) and is typically reserved for highly dynamic sites.
 
-The first option is more complicated and isn't the most typical approach, as it makes navigation different for each document. Consider the following example for rendering a page `/Something/Else`:
+:::moniker range=">= aspnetcore-11.0"
 
-* Rendered under `/Admin/B/C/`, the page is rendered with a path of `/Admin/B/C/Something/Else`.
-* Rendered under `/Admin/D/E/`, the page is rendered ***at the same path*** of `/Admin/B/C/Something/Else`.
+* Establish a consistent base path for the document and map all app resources beneath that path. Blazor Web Apps can rely on the `BasePath` component to render `<base href>` automatically, while standalone WebAssembly apps (or scenarios that always use a fixed value) configure the literal `<base>` tag in the host page.
 
-Under the first approach, routing offers <xref:Microsoft.AspNetCore.Routing.IDynamicEndpointMetadata> and <xref:Microsoft.AspNetCore.Routing.MatcherPolicy>, which in combination can be the basis for implementing a completely dynamic solution that determines at runtime about how requests are routed.
+:::moniker-end
+
+:::moniker range="< aspnetcore-11.0"
+
+* Establish a consistent base path for the document and map all app resources beneath that path. Configure the literal `<base>` tag in the host page for both server-side Blazor apps and Blazor WebAssembly apps (or scenarios that always use a fixed value).
+
+:::moniker-end
 
-For the second option, which is the usual approach taken, the app sets the base path in the document and maps the server endpoints to paths under the base. The following guidance adopts this approach.
+The remainder of this article focuses on implementing a consistent base path.
 
 ## Server-side Blazor
 
@@ -135,7 +139,13 @@ By configuring the app base path, a component that isn't in the root directory c
 
 Place the `<base>` tag in `<head>` markup ([location of `<head>` content](xref:blazor/project-structure#location-of-head-and-body-content)) before any elements with attribute values that are URLs, such as the `href` attributes of `<link>` elements.
 
-:::moniker range=">= aspnetcore-8.0"
+:::moniker range=">= aspnetcore-11.0"
+
+In many hosting scenarios, the relative URL path to the app is the root of the app. When the app runs at `/`, `<BasePath />` renders `<base href="/" />` automatically in [`<head>` content](xref:blazor/project-structure#location-of-head-and-body-content). For any other deployment path, the component emits a `<base>` element that matches the current request's path base.
+
+:::moniker-end
+
+:::moniker range=">= aspnetcore-8.0 < aspnetcore-11.0"
 
 In many hosting scenarios, the relative URL path to the app is the root of the app. In these default cases, the app's relative URL base path is `/` configured as `<base href="/" />` in [`<head>` content](xref:blazor/project-structure#location-of-head-and-body-content).
 
@@ -155,15 +165,31 @@ In many hosting scenarios, the relative URL path to the app is the root of the a
 
 * In a server-side Blazor app, use the following approach:
 
-  * Use the `<base>` tag to set the app's base path ([location of `<head>` content](xref:blazor/project-structure#location-of-head-and-body-content)):
+:::moniker range=">= aspnetcore-11.0"
+
+  * Option 1: Use the `BasePath` component to set the app's base path ([location of `<head>` content](xref:blazor/project-structure#location-of-head-and-body-content)):
+
+    ```razor
+    <BasePath />
+    ```
+
+    The component renders `<base href>` automatically based on the current request path base.
+
+::: moniker-end
+
+:::moniker range="< aspnetcore-11.0"
+
+  * Option 1: Use the `<base>` tag to set the app's base path ([location of `<head>` content](xref:blazor/project-structure#location-of-head-and-body-content)):
 
     ```html
     <base href="/CoolApp/">
     ```
 
     **The trailing slash is required.**
 
-  * Call <xref:Microsoft.AspNetCore.Builder.UsePathBaseExtensions.UsePathBase%2A> ***first*** in the app's request processing pipeline (`Program.cs`) immediately after the <xref:Microsoft.AspNetCore.Builder.WebApplicationBuilder> is built (`builder.Build()`) to configure the base path for any following middleware that interacts with the request path:
+:::moniker-end
+
+  * Option 2: Call <xref:Microsoft.AspNetCore.Builder.UsePathBaseExtensions.UsePathBase%2A> ***first*** in the app's request processing pipeline (`Program.cs`) immediately after the <xref:Microsoft.AspNetCore.Builder.WebApplicationBuilder> is built (`builder.Build()`) to configure the base path for any following middleware that interacts with the request path:
 
     ```csharp
     app.UsePathBase("/CoolApp");
