Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 42 ยท MVVM and Navigation

Shell Navigation

Navigate a .NET MAUI app with Shell: AppShell structure, flyout and tab bar, URI routes, RegisterRoute, GoToAsync with relative and absolute routes, going back, and a runnable route-table stand-in.

Almost every app has more than one screen. Shell is the navigation system that ships with .NET MAUI projects: it describes the structure of your app (flyout menu, bottom tabs, pages) in one XAML file and moves between pages with URI-style routes, similar to links on a website. This lesson shows the structure, the routing, and how a router decides what to do.

Shell cannot run on this site, so its XAML and C# are read-only. The runnable block is a labelled stand-in that implements the route-matching and back-stack rules in plain C#, so you can see how GoToAsync("//home/details") and GoToAsync("details") differ.

AppShell: the structure

A new MAUI app has AppShell.xaml. It is the root of the app (new Window(new AppShell())) and declares what the user can reach:

XML
<Shell xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
       xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
       xmlns:local="clr-namespace:ShopApp.Views"
       x:Class="ShopApp.AppShell"
       FlyoutBehavior="Disabled">

    <TabBar>
        <ShellContent Title="Home" Icon="home.png" Route="home"
                      ContentTemplate="{DataTemplate local:HomePage}" />
        <ShellContent Title="Cart" Icon="cart.png" Route="cart"
                      ContentTemplate="{DataTemplate local:CartPage}" />
        <ShellContent Title="Account" Icon="user.png" Route="account"
                      ContentTemplate="{DataTemplate local:AccountPage}" />
    </TabBar>
</Shell>

The building blocks, from the outside in:

  • Shell is the root. FlyoutBehavior is Disabled, Flyout or Locked.
  • FlyoutItem is a flyout menu entry; TabBar and Tab give bottom tabs.
  • ShellContent points at one page. Use ContentTemplate="{DataTemplate ...}", not Content, so the page is created only when first visited, and resolved from the DI container (see Dependency Injection and View Models).
  • Route gives each item a name used in URIs.

Combined, they form a hierarchy: Shell, then FlyoutItem or TabBar, then Tab, then ShellContent. The compiler inserts the missing intermediate levels, so a lone ShellContent is wrapped automatically.

flowchart TD
    S["Shell"] --> T["TabBar"]
    T --> H["ShellContent: home"]
    T --> C["ShellContent: cart"]
    T --> A["ShellContent: account"]
    H -. "pushed with GoToAsync" .-> D["details (registered route)"]

Tabs are part of the visual tree; pushed pages such as details are registered routes.

Registered routes for detail pages

Pages that are not in the Shell structure, such as a product detail page, are registered in code, usually in the AppShell constructor:

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

        Routing.RegisterRoute("details", typeof(ProductDetailPage));
        Routing.RegisterRoute("checkout", typeof(CheckoutPage));
    }
}

The route name is a string; a constant class avoids typos: public static class Routes { public const string Details = "details"; }. Routes should be unique within the app.

C#
await Shell.Current.GoToAsync("details");           // push a page on the current stack
await Shell.Current.GoToAsync("..");                // go back one page
await Shell.Current.GoToAsync("../..");             // back two pages
await Shell.Current.GoToAsync("//cart");            // absolute: switch to the cart tab
await Shell.Current.GoToAsync("//home/details");    // absolute, then push details
await Shell.Current.GoToAsync("..", animate: false);

The rules are:

  • A route that starts with // is absolute: it is resolved from the root of the Shell hierarchy and replaces the navigation stack of that tab.
  • A route without a leading slash is relative: it is pushed on top of the current page.
  • .. pops one page; it can be combined: ../details replaces the current page with details.
  • The URI may carry a query string: details?id=42. The next lesson, Navigation Parameters, Tabs and Modals, shows how to receive it.

Back buttons and the Android system back are handled automatically. To intercept them (for example to warn about unsaved changes), override OnBackButtonPressed on a page or use Shell.OnNavigating and args.Cancel().

C# Stand-in: a Shell-style router

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The first call, GoTo("//home"), is shown on the stack as home; the stand-in clamps .. at the tab root, which is a simplification: real Shell throws Relative routing to shell elements is currently not supported in some cases. Use it to understand the rules, then rely on the real framework for edge cases.

FlyoutBehavior="Flyout" adds the hamburger menu with FlyoutItem entries; Shell.FlyoutHeader, Shell.FlyoutFooter and MenuItem customise it. You can have both: tabs inside a flyout item.

XML
<FlyoutItem Title="Shop" Icon="shop.png">
    <Tab Title="Products"><ShellContent ContentTemplate="{DataTemplate local:ProductsPage}" /></Tab>
    <Tab Title="Offers"><ShellContent ContentTemplate="{DataTemplate local:OffersPage}" /></Tab>
</FlyoutItem>
<MenuItem Text="Log out" Command="{Binding LogOutCommand}" />

Attached properties on each page customise the Shell chrome: Shell.NavBarIsVisible="False", Shell.TabBarIsVisible="False" (hide the tab bar on a detail page), Shell.BackgroundColor, Shell.TitleColor, Shell.BackButtonBehavior and Shell.SearchHandler (a search box in the navigation bar).

Shell is optional. NavigationPage gives a classic stack (PushAsync, PopAsync, PopToRootAsync), TabbedPage gives tabs and FlyoutPage gives a flyout. Use them when you need the old behaviour or embed a stack in a custom layout. In new apps Shell is the better default because it standardises routes, deep links and back handling.

Passing navigation behind an interface

If many view models call Shell.Current.GoToAsync directly, they depend on the UI framework again. Wrap it:

C#
public interface INavigationService
{
    Task GoToAsync(string route, IDictionary<string, object>? parameters = null);
    Task GoBackAsync();
}

public class ShellNavigationService : INavigationService
{
    public Task GoToAsync(string route, IDictionary<string, object>? parameters = null) =>
        parameters is null
            ? Shell.Current.GoToAsync(route)
            : Shell.Current.GoToAsync(route, parameters);

    public Task GoBackAsync() => Shell.Current.GoToAsync("..");
}

Register it as a singleton, inject it, and in tests use a fake that records the route requested.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a route starting with // mean in GoToAsync?

    Double slash makes the route absolute: it is resolved from the Shell root, switching tab and resetting that stack.
  2. 2. How do you make a detail page reachable by name?

    Pages outside the Shell hierarchy are registered with Routing.RegisterRoute and then reached with GoToAsync.
  3. 3. Which GoToAsync argument goes back one page?

    Two dots pop the current page, like cd .. in a shell.
  4. 4. Why use ContentTemplate with DataTemplate in ShellContent?

    ContentTemplate delays creation until the item is visited and lets the page be built by the container.

Summary

  • AppShell declares flyout items, tabs and pages; ShellContent with ContentTemplate loads pages lazily.
  • Register detail pages with Routing.RegisterRoute and move with Shell.Current.GoToAsync.
  • //route is absolute, route is relative (push), .. goes back; query strings carry data.
  • Shell attached properties tune the navigation bar, tab bar, flyout and back button.
  • Hide navigation behind an interface so view models stay testable.

Next: Navigation Parameters, Tabs and Modals