MAUI Navigation Concepts

This document provides a comprehensive overview of navigation concepts within .NET MAUI applications. Understanding how to navigate between different pages and views is fundamental to building user-friendly and intuitive mobile and desktop applications.

Core Navigation Types

MAUI supports several primary navigation paradigms:

1. Shell Navigation

Shell provides a simplified way to implement common cross-platform application UIs, including navigation. It uses a declarative XAML structure to define the app's navigation hierarchy.

• Tab Bar: Allows users to switch between major sections of the app.
• Flyout Menu: A side menu accessible from anywhere in the app, typically used for less frequently accessed destinations.
• Hierarchical Navigation: Navigating deeper into content, such as drilling down into a list item.

Shell navigation is managed through Shell.Current.GoToAsync(). You can navigate using URIs, which map to specific pages or routes defined in your Shell application.

await Shell.Current.GoToAsync("///DetailPage");
            

2. Navigation Page

The NavigationPage is a container that manages a stack of pages. It provides a navigation bar at the top of the screen with a back button, allowing users to navigate back through the history of pages visited.

• Pushing a page onto the stack navigates forward.
• Popping a page from the stack navigates backward.
• Popping to root navigates back to the initial page in the stack.

Navigation operations are performed using methods on the Navigation property of a Page, such as PushAsync() and PopAsync().

// Push a new page
await Navigation.PushAsync(new DetailPage());

// Pop the current page
await Navigation.PopAsync();
            

3. Modal Navigation

Modal navigation is used for presenting pages that require user interaction or input without allowing the user to go back to the previous page using a standard back button. These pages are typically displayed on top of the current page.

You can present a modal page using Navigation.PushModalAsync() and dismiss it using Navigation.PopModalAsync().

// Present a modal page
await Navigation.PushModalAsync(new SettingsPage());

// Dismiss the modal page
await Navigation.PopModalAsync();
            

Routing and Navigation Parameters

MAUI's routing system allows you to define named routes for your pages, making navigation more abstract and maintainable. This is particularly powerful when using Shell.

Defining Routes

Routes can be defined in your AppShell.xaml or programmatically:

<!-- AppShell.xaml -->
<Shell ...>
    <ShellContent Title="Home" Route="HomePage" Content="{u:AppPage \{x:Type views:HomePage\}}" />
    <ShellContent Title="Details" Route="DetailPage" Content="{u:AppPage \{x:Type views:DetailPage\}}" />
</Shell>
            

Passing Parameters

You can pass data between pages during navigation using query parameters or the navigation data bag.

Query Parameters (Shell)

// Navigating to a detail page with an ID
await Shell.Current.GoToAsync($"DetailPage?id=123");
            

In the destination page, you can retrieve these parameters:

// In DetailPage.xaml.cs
[QueryProperty(nameof(ItemId), "id")]
public partial class DetailPage : ContentPage
{
    public string ItemId { get; set; }

    protected override void OnAppearing()
    {
        base.OnAppearing();
        // Use ItemId here
        Console.WriteLine($"Received Item ID: {ItemId}");
    }
}
            

Navigation Data Bag

For NavigationPage and modal navigation, you can pass parameters directly to the constructor or use a data bag.

// Pass data via constructor
await Navigation.PushAsync(new DetailPage("Item Name"));

// Pass data via NavigationData
var parameters = new Dictionary<string, object></string, object> {
    { "UserId", "user456" }
};
await Shell.Current.GoToAsync("UserProfilePage", parameters);
            

Best Practices

• Keep Navigation Simple: Avoid overly complex navigation hierarchies.
• Use Shell for Common Patterns: Leverage Shell's features for tabs, flyouts, and hierarchical navigation when appropriate.
• Clear Parameter Handling: Ensure that parameters are handled correctly and that default values are provided if necessary.
• User Experience: Design navigation flows that are intuitive and efficient for users.
• Deep Linking: Implement deep linking to allow users to navigate directly to specific content within your app from external sources.