.NET MAUI Hierarchical and Modal Navigation Step by step Implementation and Top 10 Questions and Answers
 Last Update: April 01, 2025      16 mins read      Difficulty-Level: beginner

.NET MAUI Hierarchical and Modal Navigation: A Comprehensive Guide

Navigation in applications is a critical aspect that enhances user experience by providing intuitive pathways through the app. .NET Multi-platform App UI (MAUI) offers robust support for two primary types of navigation: Hierarchical Navigation and Modal Navigation. Understanding how these navigate work is essential for developing efficient and user-friendly applications.

Hierarchical Navigation

Hierarchical Navigation allows users to move through pages in a stack, akin to browsing web pages where each link takes you deeper into the site's hierarchy. This navigation pattern is typically suited for applications with a clear hierarchical structure.

Key Concepts:

  • Page Stack: In hierarchical navigation, a stack is used to keep track of visited pages. Each new page is pushed onto the stack, and navigating back pops a page from the stack.
  • Navigation Pages: The NavigationPage class in .NET MAUI is used to implement hierarchical navigation. It manages the navigation stack and provides built-in methods for navigating between pages.

Implementation Steps:

  1. Initialize NavigationPage: Create a NavigationPage and set it as the main page of your application.

    MainPage = new NavigationPage(new HomePage());

  2. Push New Pages to the Stack: Use the PushAsync method to navigate to a new page and push it onto the stack.

    await Navigation.PushAsync(new DetailPage(item));

  3. Pop Pages from the Stack: Use the PopAsync method to navigate back to the previous page.

    await Navigation.PopAsync();

Benefits:

  • Back Navigation: Users can easily go back to the previous page using the device's back button.
  • Breadth First Traversal: Ideal for applications like news aggregators, where users explore multiple topics but can always return to their starting point.

Modal Navigation

Modal Navigation, also known as sheet or dialog navigation, is used to display pages that overlay the current page. These pages usually represent a task or a piece of information users need to deal with before continuing their journey within the application.

Key Concepts:

  • Overlay Pages: Modal pages cover the entire app's screen, focusing user attention.
  • Dismiss Method: Use the PopModalAsync method to close modal pages and return to the previous page.

Implementation Steps:

  1. Present a Modal Page: Use the PushModalAsync method to display a new page modally.

    await Navigation.PushModalAsync(new SettingsPage());

  2. Dismiss a Modal Page: Use the PopModalAsync method to close the modal page and return to the previous page.

    await Navigation.PopModalAsync();

Benefits:

  • Focus: Modal navigation draws attention to specific tasks or alerts.
  • Isolation: Users are not distracted by other parts of the app, making it ideal for login screens, forms, and settings.

Combining Hierarchical and Modal Navigation

In many applications, a combination of hierarchical and modal navigation enhances usability. For example, a user might navigate through a series of hierarchical pages, then open a modal configuration page to adjust settings, and return to the hierarchical flow afterward.

Example Scenario:

  • Hierarchical Navigation: Users navigate through a list of articles, each leading to a detailed view.
  • Modal Navigation: From the detailed view, users can open a modal settings page to adjust font size or theme.

Implementation Tips:

  • State Management: Ensure that the app's state is properly managed when switching between different types of navigation.
  • Consistent UI: Maintain consistent navigation bar appearances and behaviors across different pages to improve user experience.
  • Performance Optimization: Consider caching pages that are frequently visited to improve performance.

Important Information

  • Back Button Handling: Pay attention to how back buttons work in each navigation mode. In hierarchical navigation, they pop the stack; in modal navigation, they dismiss the modal page.
  • Memory Management: Be cautious about memory usage, especially with modal navigation, as overlapping pages can consume significant resources.
  • Customization: Customize navigation bars and transitions for a more tailored user experience.

By understanding and leveraging hierarchical and modal navigation in .NET MAUI, developers can create applications that are not only efficient but also engaging and intuitive. Utilizing these navigation patterns effectively ensures that users can easily navigate through your app's features and find the information they need quickly and effortlessly.

.NET MAUI Hierarchical and Modal Navigation: Step-by-Step Guide for Beginners

Navigating through pages in a .NET Multi-platform App UI (MAUI) application is crucial for building user-friendly interfaces. .NET MAUI supports two primary types of navigation: Hierarchical and Modal. Hierarchical navigation involves pushing new pages onto a stack, allowing users to return to the previous page, while Modal navigation brings up a page over the existing interface, often serving as a dialog or confirmation prompt. This guide will walk you through the basics of setting routes, running the application, and understanding data flow in both types of navigation.

1. Setting Up Your .NET MAUI Application

Before we dive into navigation, let's set up a basic .NET MAUI application.

  • Install .NET 7 SDK: Ensure you have the latest .NET 7 SDK installed on your machine.
  • Create a New Project: Open a terminal or command prompt and run the following command to create a new .NET MAUI project: 
    dotnet new maui -n NavigationSample
  • Navigate to the Project: Change directory to the newly created project. 
    cd NavigationSample
  • Run the Application: Build and run the default application using the following command: 
    dotnet build
dotnet run

2. Hierarchical Navigation

Hierarchical navigation involves navigating between pages in a way that resembles a stack. You can "push" a page onto the stack or "pop" a page off the stack.

Step 1: Define the Shell

In .NET MAUI, a Shell serves as the root layout and is often used for navigation. Define a shell in your App.xaml or App.xaml.cs.

<!-- App.xaml -->
<Application xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="NavigationSample.App">
    <Application.Resources>
        <ResourceDictionary>
            <!-- Add your app's resources here -->
        </ResourceDictionary>
    </Application.Resources>
    <Shell>
        <FlyoutItem Title="Main Page" Route="MainPage" Icon="dotnet_bot.png">
            <ShellContent>
                <pages:MainPage />
            </ShellContent>
        </FlyoutItem>
    </Shell>
</Application>

Step 2: Add a New Page

Add a new page to your project, for example, SecondPage.xaml.

<!-- SecondPage.xaml -->
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="NavigationSample.SecondPage"
             Title="Second Page">
    <Label Text="Welcome to the Second Page!" 
           HorizontalOptions="Center"
           VerticalOptions="CenterAndExpand" />
</ContentPage>

Step 3: Set the Route

Define the route for SecondPage in the AppShell.xaml or AppShell.xaml.cs.

<!-- AppShell.xaml -->
<Shell xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
       xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
       x:Class="NavigationSample.AppShell">
    <FlyoutItem Title="Main Page" Route="MainPage" Icon="dotnet_bot.png">
        <ShellContent>
            <pages:MainPage />
        </ShellContent>
    </FlyoutItem>
    <FlyoutItem Title="Second Page" Route="SecondPage">
        <ShellContent>
            <pages:SecondPage />
        </ShellContent>
    </FlyoutItem>
</Shell>

Step 4: Navigating to SecondPage

In your MainPage.xaml.cs, add a button that navigates to SecondPage.

// MainPage.xaml.cs
public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
        NavigationButton.Clicked += (s, e) => OnNavigateButtonClicked();
    }

    private async void OnNavigateButtonClicked()
    {
        await Shell.Current.GoToAsync("//SecondPage");
    }
}

Step 5: Running the Application

Build and run your application. You should see a button to navigate to SecondPage. Clicking this button will push SecondPage onto the navigation stack.

3. Modal Navigation

Modal navigation presents a new page over the current page, often used for dialog boxes or confirmation prompts.

Step 1: Add a New Modal Page

Create a new page for modal navigation, for example, ModalPage.xaml.

<!-- ModalPage.xaml -->
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="NavigationSample.ModalPage"
             Title="Modal Page">
    <StackLayout>
        <Label Text="This is a Modal Page!" 
               HorizontalOptions="Center"
               VerticalOptions="CenterAndExpand" />
        <Button Text="Close"
                Clicked="OnCloseButtonClicked" 
                HorizontalOptions="Center" 
                VerticalOptions="End" />
    </StackLayout>
</ContentPage>

Step 2: Navigate to the Modal Page

In your MainPage.xaml.cs, add a button to open ModalPage.

// MainPage.xaml.cs
public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
        ModalButton.Clicked += (s, e) => OnModalButtonClicked();
    }

    private async void OnModalButtonClicked()
    {
        await Navigation.PushModalAsync(new ModalPage());
    }
}

Step 3: Close the Modal Page

In your ModalPage.xaml.cs, handle the button click to close the modal page.

// ModalPage.xaml.cs
public partial class ModalPage : ContentPage
{
    public ModalPage()
    {
        InitializeComponent();
    }

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

4. Data Flow

Data flow in .NET MAUI can be managed through various mechanisms such as bindings, messaging, or directly passing data.

Step 1: Binding Data

Bind data from your view model to your views using data bindings.

<!-- SecondPage.xaml -->
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="NavigationSample.SecondPage"
             BindingContext="{Binding Source={x:Static local:ViewModels.SecondViewModel}}">
    <Label Text="{Binding Title}" 
           HorizontalOptions="Center"
           VerticalOptions="CenterAndExpand" />
</ContentPage>

Step 2: Passing Data to Modal Page

Pass data when navigating to a modal page using the query parameter feature.

// MainPage.xaml.cs
private async void OnModalButtonClicked()
{
    await Navigation.PushModalAsync(new ModalPage() { BindingContext = new ModalViewModel("Hello Modal!") });
}

Step 3: Messaging Center

Use the MessagingCenter to send messages between components.

// Message sender in MainPage.xaml.cs
MessagingCenter.Send((object)this, "MessageSent", "Hello from Main Page!");

// Message receiver in ModalPage.xaml.cs
protected override void OnAppearing()
{
    MessagingCenter.Subscribe<object, string>(this, "MessageSent", (s, arg) =>
    {
        Label.Text = arg;
    });
}

Conclusion

Understanding and implementing navigation types in .NET MAUI is essential for building responsive and user-friendly applications. This guide covered setting routes, handling hierarchical and modal navigation, and managing data flow. With these concepts, you can create sophisticated navigation structures in your .NET MAUI applications. Practice by building more complex navigation scenarios and experimenting with different data binding techniques. Happy coding!

Top 10 Questions and Answers on .NET MAUI Hierarchical and Modal Navigation

1. What is Hierarchical Navigation in .NET MAUI, and when should it be used?

Answer: Hierarchical navigation in .NET MAUI is a pattern used to navigate between pages in a way that creates a stack. This means you navigate from one page to another, pushing the new page onto the navigation stack, and can return back to the previous page by popping it from the stack. It is suitable for applications with a clear forward and backward flow, such as navigating through a series of sequential steps in a wizard or browsing through a list of items.

2. What is Modal Navigation in .NET MAUI, and how does it differ from Hierarchical Navigation?

Answer: Modal navigation in .NET MAUI involves displaying a page modally, which means it is shown on top of the current page, typically in a manner that requires the user to interact with it before being able to go back to the previous page. Unlike hierarchical navigation, which uses a stack, modal navigation can be used for pages that should temporarily block the user from interacting with the underlying pages, such as displaying a form, alert, or settings dialog. Modal navigation often involves presenting a page that is more like a dialog or a popup rather than a new step in a flow.

3. How can I perform Hierarchical Navigation in .NET MAUI using Shell?

Answer: Shell in .NET MAUI simplifies hierarchical navigation. You can set up routes and use them to navigate between pages. Here’s a basic example:

  1. Define routes in your AppShell.xaml or AppShell.xaml.cs:

    <Shell>
    <ShellContent Route="MainPage" ContentTemplate="{DataTemplate local:MainPage}" />
    <ShellContent Route="DetailsPage" ContentTemplate="{DataTemplate local:DetailsPage}" />
</Shell>

  2. Navigate to a page using Shell.Current.GoToAsync:

    private async void Button_Clicked(object sender, EventArgs e)
{
    await Shell.Current.GoToAsync(nameof(DetailsPage));
}

4. Can I pass parameters during Hierarchical Navigation in .NET MAUI?

Answer: Yes, you can pass parameters in hierarchical navigation. You define route parameters in your route definition and then pass them when navigating:

  1. Define a route with parameters in AppShell.xaml:

    <Route Route="DetailsPage/{id}" ViewType="{x:Type local:DetailsPage}" />

  2. Navigate and pass a parameter:

    private async void Button_Clicked(object sender, EventArgs e)
{
    await Shell.Current.GoToAsync($"DetailsPage/123");
}

  3. Retrieve the parameter in the target page:

    protected override void OnNavigatedTo(NavigatedToEventArgs args)
{
    base.OnNavigatedTo(args);
    if (args.Parameter is string id)
    {
        // Use the parameter
    }
}

5. How can I handle navigation events in .NET MAUI?

Answer: INavigation provides events such as Navigated, Navigating, and NavigatedTo. You can subscribe to these events in your pages to handle navigation-related tasks.

protected override void OnAppearing()
{
    base.OnAppearing();
    ((AppShell)Shell.Current).Navigated += OnNavigated;
}

protected override void OnDisappearing()
{
    base.OnDisappearing();
    ((AppShell)Shell.Current).Navigated -= OnNavigated;
}

private void OnNavigated(object sender, NavigatedEventArgs e)
{
    // Handle navigation event
}

6. What is a Shell Flyout in .NET MAUI, and how does it relate to Hierarchical Navigation?

Answer: A Shell Flyout in .NET MAUI is a navigation menu that allows users to switch between different root pages of your application. It is often used for top-level navigation and is integrated with hierarchical navigation. You define flyout items in AppShell.xaml, and each item can represent a different page or stack of pages.

<Shell>
    <Shell.FlyoutHeader>
        <Label Text="Main Menu" TextColor="White" BackgroundColor="Blue" HorizontalOptions="Center" Margin="0,20,0,0" />
    </Shell.FlyoutHeader>
    <FlyoutItem Title="Home" FlyoutDisplayOptions="AsSingleItem" Icon="home.png" Route="MainPage" />
    <FlyoutItem Title="Settings" FlyoutDisplayOptions="AsSingleItem" Icon="settings.png" Route="SettingsPage" />
</Shell>

7. How do I implement Modal Navigation in .NET MAUI?

Answer: Modal navigation can be performed using Shell.Current.GoToAsync with a modal prefix in the route:

  1. Push a modal page:

    private async void Button_Clicked(object sender, EventArgs e)
{
    await Shell.Current.GoToAsync(nameof(ModalPage), true);
}

  2. Dismiss a modal page:

    private async void DismissButton_Clicked(object sender, EventArgs e)
{
    await Shell.Current.Navigation.PopModalAsync();
}

8. How can I handle navigation results in .NET MAUI?

Answer: You can handle navigation results by using asynchronous methods and the Navigation.PopAsync return value:

  1. Push a page that expects a result:

    var result = await Shell.Current.Navigation.PushAsync(new ResultPage());

  2. Pass a result back when navigating back:

    private async void Button_Clicked(object sender, EventArgs e)
{
    await Navigation.PopAsync(true, "ResultData");
}

  3. Handle the result in the calling page:

    protected override async void OnNavigatingFrom(NavigatingFromEventArgs args)
{
    if (args.Result != null && args.Result is string resultData)
    {
        // Handle the result
    }
}

9. Can I use Tab Bar Navigation in .NET MAUI, and how does it integrate with Hierarchical Navigation?

Answer: Yes, Tab Bar Navigation in .NET MAUI is supported through Shell. Each tab can represent a different root page or stack of pages, integrating seamlessly with hierarchical navigation.

  1. Define tabs in AppShell.xaml:

    <TabBar>
    <ShellContent Title="Tab1" Icon="tab1.png" Route="Tab1Page" ContentTemplate="{DataTemplate local:Tab1Page}" />
    <ShellContent Title="Tab2" Icon="tab2.png" Route="Tab2Page" ContentTemplate="{DataTemplate local:Tab2Page}" />
</TabBar>

  2. Navigate within each tab using hierarchical navigation.

10. What are some best practices when implementing Hierarchical and Modal Navigation in .NET MAUI?

Answer:

  • Define Routes Clearly: Use meaningful and consistent route names.
  • Use Shell: Leverage Shell for a clean and efficient navigation structure.
  • Handle Back Button: Ensure proper handling of the back button to provide a seamless user experience.
  • Manage State: Be mindful of page state, especially when using modal navigation.
  • Animate Transitions: Use animations to improve user experience, but keep them subtle and performant.
  • Optimize Performance: Efficiently manage navigation performance, especially with larger or complex page transitions.
  • Use ViewModel Navigation: Implement MVVM patterns to separate UI logic from navigation logic.

By understanding and implementing these patterns and best practices, you can create a robust and intuitive navigation system in your .NET MAUI applications.