.NET MAUI Documentation

Introduction to Navigation

Understanding the fundamental concepts of navigation in .NET MAUI is crucial for building well-structured and user-friendly applications. MAUI provides a robust navigation system that abstracts away platform-specific implementations, allowing you to focus on your app's logic.

Key components include:

• NavigationPage: Manages a stack of pages, allowing for push and pop operations.
• Shell: A framework that simplifies common application architecture patterns, including navigation.
• Page Navigation: The act of transitioning between different pages in your application.

Basic Navigation (Push/Pop)

The most common form of navigation involves pushing a new page onto the navigation stack and popping the current page off. This is typically handled by the NavigationPage.

To push a new page:

async void NavigateToNextPage(object sender, EventArgs e)
{
    await Navigation.PushAsync(new NextPage());
}
                

To go back to the previous page:

async void GoBack(object sender, EventArgs e)
{
    await Navigation.PopAsync();
}
                

Modal Navigation

Modal pages are used for tasks that require the user's immediate attention or input, and typically dismiss the current context. They are presented without being part of the navigation stack.

To present a modal page:

async void PresentModalPage(object sender, EventArgs e)
{
    await Navigation.PushModalAsync(new MyModalPage());
}
                

To dismiss a modal page:

async void DismissModal(object sender, EventArgs e)
{
    await Navigation.PopModalAsync();
}
                

Tabbed Navigation

Tabbed navigation allows users to switch between different sections of your application using tabs, typically located at the bottom of the screen.

This is implemented using the TabbedPage in XAML:

<TabbedPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
            xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
            xmlns:pages="clr-namespace:YourApp.Pages"
            x:Class="YourApp.MainTabbedPage"
            Title="My App Tabs">

    <pages:HomePage Title="Home" />
    <pages:SettingsPage Title="Settings" />
    <pages:ProfilePage Title="Profile" />

</TabbedPage>
                

Flyout Navigation (Hamburger Menu)

Flyout navigation, often referred to as a hamburger menu, provides a hidden pane that slides out from the side, typically offering a list of navigation options.

This is commonly achieved using the Shell framework.

In your AppShell.xaml:

<Shell xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
       xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
       xmlns:local="clr-namespace:YourApp"
       x:Class="YourApp.AppShell"
       Title="YourApp">

    <Shell.Items>
        <-- Your content here, often using FlyoutItem -->
        <FlyoutItem Title="Home" Icon="house.png">
            <ShellContent ContentTemplate="{DataTemplate local:HomePage}" />
        </FlyoutItem>
        <FlyoutItem Title="About" Icon="info.png">
            <ShellContent ContentTemplate="{DataTemplate local:AboutPage}" />
        </FlyoutItem>
    </Shell.Items>

</Shell>
                

Passing Data Between Pages

Often, you'll need to pass data when navigating to another page. This can be done through constructors or by using navigation parameters.

Using constructors:

// In the page you are navigating from
var person = new Person { Name = "Alice", Age = 30 };
await Navigation.PushAsync(new DetailPage(person));

// In DetailPage.xaml.cs
public partial class DetailPage : ContentPage
{
    public DetailPage(Person person)
    {
        InitializeComponent();
        // Use the person object here
        MyLabel.Text = $"{person.Name}, {person.Age}";
    }
}
                

Advanced Routing

.NET MAUI Shell offers a powerful routing system that allows you to navigate to pages using friendly URIs. This decouples navigation logic from UI elements.

Registering routes in AppShell.xaml.cs:

public partial class AppShell : Shell
{
    public AppShell()
    {
        InitializeComponent();
        Routing.RegisterRoute("details", typeof(DetailPage));
        Routing.RegisterRoute("settings/advanced", typeof(AdvancedSettingsPage));
    }
}
                

Navigating with routes:

// Navigate to a simple route
await Shell.Current.GoToAsync("details");

// Navigate with query parameters
await Shell.Current.GoToAsync($"details?id=123&name=Bob");

// Navigate to a nested route
await Shell.Current.GoToAsync("settings/advanced");
                

Best Practices

• Keep Navigation Simple: Avoid deeply nested navigation hierarchies.
• Use Clear Labels: Ensure titles and tab labels are descriptive.
• Provide Feedback: Indicate when navigation is in progress, especially for long operations.
• Handle Back Navigation: Ensure the back button behaves as expected.
• Leverage Shell: For most applications, .NET MAUI Shell simplifies navigation significantly.
• Consider User Experience: Design navigation flows that are intuitive and efficient for your target audience.