Shell Navigation in .NET MAUI

This tutorial guides you through implementing navigation in your .NET MAUI application using Shell. Shell simplifies the development of cross-platform applications by providing a consistent navigation experience.

Understanding Shell Navigation

MAUI Shell abstracts the complexity of navigation patterns like tab bars, flyouts, and hierarchical navigation. It uses a URI-based routing system that allows you to navigate to specific pages by their route.

Setting Up Your Project

Ensure you have a .NET MAUI project created. If not, you can create one using the .NET CLI:

dotnet new maui -n MyMauiApp

Defining Routes

Routes are typically defined in your AppShell.xaml or AppShell.xaml.cs file. You can associate routes with specific pages.

In AppShell.xaml:

<?xml version="1.0" encoding="UTF-8" ?>
<Shell xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
       xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
       xmlns:local="clr-namespace:MyMauiApp"
       x:Class="MyMauiApp.AppShell"
       Shell.FlyoutBehavior="Disabled">

    <!-- Tabbed pages -->
    <TabBar>
        <Tab Title="Home" Icon="home_icon.png">
            <ShellContent ContentTemplate="{DataTemplate local:HomePage}" />
        </Tab>
        <Tab Title="About" Icon="info_icon.png">
            <ShellContent ContentTemplate="{DataTemplate local:AboutPage}" />
        </Tab>
    </TabBar>

    <!-- ShellItem for a simple page -->
    <ShellItem Route="details">
        <ShellContent ContentTemplate="{DataTemplate local:DetailsPage}" />
    </ShellItem>

</Shell>

In AppShell.xaml.cs:

namespace MyMauiApp;

public partial class AppShell : Shell
{
    public AppShell()
    {
        InitializeComponent();

        // Registering a route programmatically
        Routing.RegisterRoute("details/sub", typeof(SubDetailsPage));
    }
}

Navigating Between Pages

You can initiate navigation using Shell.Current.GoToAsync(). This method supports various navigation scenarios, including navigating to registered routes.

Basic Navigation

Navigate to a page with a registered route:

// Navigate to the page registered with the "details" route
await Shell.Current.GoToAsync("details");

Navigation with Parameters

Pass data to a page during navigation:

await Shell.Current.GoToAsync("details", new Dictionary<string, object>
{
    {"ItemId", 123}
});

In your target page's code-behind (e.g., DetailsPage.xaml.cs), you can handle these parameters in the OnNavigatedTo method:

public partial class DetailsPage : ContentPage
{
    public DetailsPage()
    {
        InitializeComponent();
    }

    protected override void OnNavigatedTo(NavigatedToEventArgs args)
    {
        base.OnNavigatedTo(args);

        if (args.Navigation.ExtraData.TryGetValue("ItemId", out object itemId))
        {
            int id = (int)itemId;
            // Use the itemId
            ItemIdLabel.Text = $"Item ID: {id}";
        }
    }
}

Navigation to Tabs

You can navigate to specific tabs:

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

Navigating Back

To navigate back to the previous page:

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

Custom Navigation Transitions

Shell allows you to define custom animations for navigation. This is done by specifying animation properties in the route registration or using attached properties.

Summary

Shell navigation in .NET MAUI offers a powerful and flexible way to manage your application's user interface flow. By leveraging its URI-based routing and simplification of navigation patterns, you can build engaging cross-platform experiences more efficiently.

Microsoft Learn