Navigation

Website navigation allows visitors to make another as the current display page, jumping from one page to another and continue browsing forward. This tutorial includes:

• Types of navigation.
• Navigate by link.
• Navigate by code.
• Detect navigation.

You can download the example code used in this topic on GitHub.

Types of navigation

You and the users can control which page to navigate to. When the users click on a link, that is navigating by link. When you want to do some logic and navigate to a specific page respectively, that is navigating by code.

Navigate by link

To create a link for the user to click, you have 2 options: NavLink component and <a> tag.

<a> tag

<a> tag is useful when you want to create a simple link, or you want to customize your logic which NavLink cannot provide. An example of <a> tag:

<a href="page-3">Page 3 (HTML tag)</a>

NavLink component

NavLink component is useful when you want to build a navigation bar. With NavLink component, you can highlight the menu of the current page of the current page or relative pages without any code. For example, when you are using Blazor School, at the right corner of the website, you will see the menu Tutorial is being highlighted.

To create a link with NavLink, you need to use specify the href for the NavLink. For example:

<NavLink href="page-1-1">Page 1.1</NavLink>

With the above code, Blazor WebAssembly will generate the following HTML tag:

<a href="page-1-1">Page 1.1</a>

Highlight current menu with NavLink

Each menu links to a URL, if the browser URL matches the menu URL, the link will have some CSS classes to highlight itself. To determine when the browser URL matches with the link, use parameter Match of NavLink component. In case you don't specify the Match parameter, Blazor WebAssembly will assume it is NavLinkMatch.Prefix. Here is an example of using Match parameter:

<NavLink href="page-2" Match="NavLinkMatch.All">Page 2</NavLink>

The NavLinkMatch enum

The Match parameter use the NavLinkMatch as its value. The NavLinkMatch enum has 2 values: Prefix and All.

For NavLinkMatch.Prefix value, it will be a match if the browser URL starts with the href value of NavLink and vice versa.

For NavLinkMatch.All value, it will be a match if the browser URL as sane as the href value of NavLink and vice versa.

Custom highlighting CSS classes

When the browser URL matches with a NavLink, the link will be highlighted with the CSS class active by default. For example, when a link matches with the browser URL, Blazor WebAssembly will render the following tag:

<a href="page-1" class="active">Page 1</a>

If you want to change the highlighting CSS class, you can use ActiveClass parameter of NavLink component. Assuming you have the following NavLink tag:

<NavLink href="page-1" ActiveClass="btn btn-primary">Page 1</NavLink>

When the browser URL is https://localhost:XXXX/page-1, Blazor WebAssembly will render the following tag:

<a href="page-1" class="btn btn-primary">Page 1</a>

Navigate by code

To navigating by code, you need to inject NavigationManager to your component and use the injected instance to navigate to another page. For example:

@inject NavigationManager NavigationManager

<button class="btn btn-primary" type="button" @onclick="Navigate">To Homepage</button>

@code {
    public void Navigate()
    {
        NavigationManager.NavigateTo("/");
    }
}

Reload page on navigating

Blazor WebAssembly is an SPA framework, which means the browser will not reload the page when the users navigate through pages. However, you can force the browser to reload when the users navigate to a specific page by passing forceReload parameter to the method NavigateTo. For example:

NavigationManager.NavigateTo("/", forceLoad: true);

Navigating without storing history

Each time the browser changes its URL, the browser will automatically store the previous page to the history stack. When the user presses the back/forward button of the browser, the browser will go back/forward based on this history stack. The following image is an example of the browser history stack:

To navigate without storing the history stack, you can pass replace parameter to the method NavigateTo. For example:

NavigationManager.NavigateTo("/", replace: false);

Detect navigation

You can detect a navigation whether triggered by code or by a link in Blazor WebAssembly with LocationChange event of NavigationManager. The following code demonstrate how to listen to the LocationChange event:

@inject NavigationManager NavigationManager
@inject IJSRuntime JSRuntime
@implements IDisposable

<h3>Current URL: @NavigationManager.Uri</h3>

@code {
    protected override void OnInitialized()
    {
        NavigationManager.LocationChanged += OnLocationChanged;
    }

    private void OnLocationChanged(object? sender, LocationChangedEventArgs eventArgs)
    {
        JSRuntime.InvokeVoidAsync("alert", "Navigation detected!");
        InvokeAsync(StateHasChanged);
    }

    public void Dispose()
    {
        NavigationManager.LocationChanged -= OnLocationChanged;
    }
}

Always remember to unsubscribe the event in Dispose method when you subscribe to any event.