API proposal for `Router.NotFoundPage`

[ilonatommy]

Background and Motivation

Blazor’s Router component determines which page to display based on the current route. Previously, customizing the content shown for unmatched routes (i.e., 404 “not found” pages) required using the NotFound render fragment, which could be limiting in scenarios where you want to display a dedicated component or page type or unify the not-found experience for non-blazor pages re-execution.

This proposal introduces a new NotFoundPage property on Microsoft.AspNetCore.Components.Routing.Router, allowing developers to specify a component type to render when no route matches. This provides a more flexible and reusable way to handle “not found” scenarios in Blazor applications.

Proposed API

namespace Microsoft.AspNetCore.Components.Routing
{
    public class Router : IComponent
    {
+       public Type NotFoundPage { get; set; }
    }
}

Usage Examples

<Router AppAssembly="@typeof(Program).Assembly"
        NotFoundPage="@typeof(MyCustomNotFoundComponent)">
</Router>

Where MyCustomNotFoundComponent is a Blazor component with a route that you define, for example:

@path "/my-not-found"
<h1>Page Not Found</h1>
<p>The page you are looking for does not exist.</p>

Alternative Designs

• The existing NotFound render fragment allows inline markup for unmatched routes, but does not support specifying a reusable component type and does not render for corner cases, like started response in streaming rendering.
• Other frameworks often allow specifying a “not found” page by type or path, which this proposal aligns with.
• An alternative could have been to enhance the NotFound fragment to accept a component type, but a dedicated property is more explicit and discoverable.

Risks

• If both NotFound and NotFoundPage are set, there may be ambiguity about which takes precedence. NotFoundPage does. Documentation should clarify the behavior.
• If the specified NotFoundPage type is not a valid Blazor component or is a component without RouteAttribute, a runtime error will occur.