Api proposal for NavLink.ShouldMatch

[javiercn]

Overview and Motivation

In Blazor applications, navigation links using NavLink with Match=NavLinkMatch.All don't appear selected when query strings or fragments are appended to the URL. Users reported this as confusing when navigating in applications with query parameters.

The issue occurs because the current implementation performs exact matching including query strings and fragments. After discussion, it was determined that the original intention of NavLinkMatch.All was to match the path portion only, ignoring queries and fragments. This proposal adds a virtual method to allow customization of this behavior.

Proposed API

namespace Microsoft.AspNetCore.Components.Routing
{
    public partial class NavLink : IComponent, IDisposable
    {
        protected virtual bool ShouldMatch(string currentUriAbsolute)
        {
        }
    }
}

Usage Examples

Developers can override the ShouldMatch method to implement custom matching behavior:

public class CustomNavLink : NavLink
{
    protected override bool ShouldMatch(string currentUriAbsolute)
    {
        bool baseMatch = base.ShouldMatch(currentUriAbsolute);
        if (!baseMatch || string.IsNullOrEmpty(hrefAbsolute) || Match != NavLinkMatch.All)
        {
            return baseMatch;
        }

        if (NormalizeUri(hrefAbsolute) == NormalizeUri(currentUriAbsolute))
        {
            return true;
        }
        return false;
    }    
}

Alternative Designs

1. Adding a property to control query string matching behavior was considered in issue fix NavLink with query string can't be selected correctly #32168, but this approach would not handle fragments or other URL elements consistently.
2. A specialized version of NavLink (e.g., NavLinkIgnoreQuery) was considered, but the virtual method approach provides more flexibility for developers to create custom implementations.

Risk Considerations

This behavior change might break existing applications that rely on the current exact matching behavior, including query strings. Links may start or stop highlighting differently after upgrading.

To mitigate this risk, the old behavior can be preserved by setting the following app context switch:

Microsoft.AspNetCore.Components.Routing.NavLink.EnableMatchAllForQueryStringAndFragment

[halter73]

API Review Notes:

• An alternative would be introducing something like NavLinkMatch.FullPath for the new behavior rather than changing NavLinkMatch.All behavior. Should we do this?
  • No because the old NavLinkMatch.All behavior is bad and relies on query string order.
• Is ShouldMatch useful?
  • It gives you granularity and allows you to match query strings in a reasonable way.
  • There are other reasons to provide custom matching logic, e.g., you want /stephen-halter to match the "My Profile" link if the user is logged in as Stephen.
• We should rename argument from currentUriAbsolute to uriAbsolute so that if we wanted we could call it with a URI that isn't the current one.
• What about the Microsoft.AspNetCore.Components.Routing.NavLink.EnableMatchAllForQueryStringAndFragment switch name?
  • DisableMatchAllIgnoresQueryAndHash?
  • Seems good as-is. It's long but clear and avoids the double negative

NOTE: currentUriAbsolute was changed to uriAbsolute. There are no other changes from the proposal.

namespace Microsoft.AspNetCore.Components.Routing;

public partial class NavLink : IComponent, IDisposable
{
+    protected virtual bool ShouldMatch(string uriAbsolute)
+    {
+    }
}