MAUI Navigation

.NET MAUI (Multi-platform App UI) provides robust navigation capabilities to manage the flow between different pages in your application. This document covers the fundamental concepts and common patterns for implementing navigation in your MAUI apps.

Page Navigation Types

.NET MAUI supports several primary navigation patterns:

• Page-based navigation: The most common form, where users navigate between distinct pages. This is typically managed using a NavigationPage.
• Modal navigation: Used for pages that require user interaction without disrupting the main flow, such as displaying a form or a confirmation dialog.
• Tabbed navigation: Allows users to switch between different sections of an application using tabs, commonly found at the bottom or top of the screen.
• Flyout navigation: Implemented using a Shell and provides a side menu (often called a "hamburger menu") for navigating between major sections.

NavigationPage

The NavigationPage is a container that manages a stack of pages. When you push a new page onto the stack, it appears on top of the current page. When you pop a page, it's removed from the stack, revealing the page beneath it.

Pushing a Page

To navigate to a new page, you can use the PushAsync method:

await Navigation.PushAsync(new DetailPage());
            

Popping a Page

To return to the previous page:

await Navigation.PopAsync();
            

Popping to Root

To return to the first page in the navigation stack:

await Navigation.PopToRootAsync();
            

Setting the Root Page

When you create a new MAUI app, you typically set the root of your application's page hierarchy. If you're using NavigationPage, you wrap your initial page:

public partial class App : Application
{
    public App()
    {
        InitializeComponent();

        MainPage = new NavigationPage(new MainPage());
    }
}
            

Modal Navigation

Modal pages are displayed modally, meaning they overlay the current page and require the user to interact with them before returning to the previous page. Use the Navigation.PushModalAsync and Navigation.PopModalAsync methods.

Presenting a Modal Page

await Navigation.PushModalAsync(new ModalEntryPage());
            

Dismissing a Modal Page

await Navigation.PopModalAsync();
            

Shell Navigation

.NET MAUI Shell simplifies application structure and navigation. It provides built-in support for flyout menus and tabbed interfaces.

Creating a Shell Application

A Shell application typically uses a Shell object as its MainPage, which contains FlyoutItems or Tabs to define the app's structure.

<!-- AppShell.xaml -->
<Shell xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
       ...>
    <FlyoutItem Title="Home"
                Icon="dotnet_bot.png">
        <ShellContent ContentTemplate="{DataTemplate local:HomePage}" />
    </FlyoutItem>

    <Tab Title="About"
         Icon="info.png">
        <ShellContent ContentTemplate="{DataTemplate local:AboutPage}" />
    </Tab>
</Shell>
            

Navigating within Shell

Navigation within a Shell app can be done using URIs or by pushing/popping pages programmatically.

// Navigate to a page using a URI
await Shell.Current.GoToAsync("//Settings/Profile");

// Navigate to a new page using its type
await Shell.Current.Navigation.PushAsync(new SomeOtherPage());
            

Navigation Parameters

You can pass data between pages during navigation. For NavigationPage, you can pass parameters to the page's constructor or use properties. For Shell, you can use query parameters in the URI.

Using Constructors

// In MainPage.xaml.cs
private async void Button_Clicked(object sender, EventArgs e)
{
    await Navigation.PushAsync(new DetailPage("Some Identifier"));
}

// In DetailPage.xaml.cs
public DetailPage(string id)
{
    InitializeComponent();
    // Use the 'id' parameter
}
            

Using Shell Query Parameters

// Navigate with query parameters
await Shell.Current.GoToAsync($"Details?itemId=123&category=electronics");

// In the target page (e.g., DetailsPage)
[QueryProperty("ItemId", "itemId")]
[QueryProperty("Category", "category")]
public partial class DetailsPage : ContentPage
{
    public string ItemId { get; set; }
    public string Category { get; set; }

    protected override void OnNavigatedTo(NavigatedToEventArgs args)
    {
        base.OnNavigatedTo(args);
        // Use ItemId and Category properties
    }
}
            

Navigation Events

.NET MAUI pages emit navigation events that you can hook into:

• OnNavigatingFrom: Fired just before the page is navigated away from.
• OnNavigatedTo: Fired after the page has been navigated to.
• OnNavigatingBack: Fired when the user navigates back to the page.
• OnNavigatedBack: Fired after the user has navigated back to the page.

These methods can be overridden in your page classes to perform actions such as saving data or updating the UI.