Implement page navigation in .NET MAUI apps using Shell. Shell provides URI-based navigation, a flyout menu, tab bars, and a four-level visual hierarchy — all configured declaratively in XAML.
\nGoToAsyncmaui-data-bindingmaui-dependency-injectionNavigationPage without Shell (different navigation API)AppShell.xaml as the root shellContentPage) to navigate betweenThese are the Shell-specific decisions that are easy to get wrong. Apply them\nwhenever they are relevant to what the user asked.
\n| Situation | \nDo this | \nNot this | \n
|---|---|---|
Declaring pages in AppShell.xaml | \nWith xmlns:views=\"clr-namespace:MyApp.Views\" declared: <ShellContent ContentTemplate=\"{DataTemplate views:MyPage}\" /> — the page is created on first navigation | \n<ShellContent><views:MyPage /></ShellContent>, which constructs every page at startup | \n
| Navigating to a page not in the visual hierarchy | \nRouting.RegisterRoute(\"details\", typeof(DetailsPage)) first | \nCalling GoToAsync(\"details\") unregistered — it throws at runtime | \n
| Receiving navigation parameters | \nImplement IQueryAttributable on the ViewModel | \nImplementing it on the Page, which splits state from the BindingContext | \n
| Passing a whole object | \nShellNavigationQueryParameters | \nSerialising the object into the query string | \n
Any GoToAsync call | \nawait it | \nFire-and-forget — exceptions are swallowed and navigation races | \n
| Confirming before back navigation | \nShellNavigatingEventArgs.GetDeferral() … deferral.Complete() | \nBlocking synchronously on the dialog task | \n
| Detecting back navigation | \nCheck e.Source == ShellNavigationSource.Pop | \nAssuming every navigation is a back action | \n
Do not propose NavigationPage / PushAsync solutions for a Shell app, and do\nnot restructure a working AppShell hierarchy unless the user asked.
Answer narrowly, but completely. Staying on topic does not mean being terse. When\nyou show a navigation change, include the pieces needed to run it: the AppShell.xaml\nmarkup and the Routing.RegisterRoute call, or the GoToAsync call and the\nreceiving IQueryAttributable / [QueryProperty] code. Where two approaches are both\nvalid (query string vs ShellNavigationQueryParameters), show both and say when each\nfits — a single snippet the user still has to complete is a worse answer.
Shell uses a four-level hierarchy. Each level wraps the one below it:
\nShell\n ├── FlyoutItem / TabBar (top-level grouping)\n │ ├── Tab (bottom-tab grouping)\n │ │ ├── ShellContent (page slot → ContentPage)\n │ │ └── ShellContent (multiple = top tabs)\n │ └── Tab\n └── FlyoutItem / TabBar\nTab childrenShellContent; multiple children produce top tabsContentPageYou can omit intermediate wrappers. Shell auto-wraps:
\n| You write | \nShell creates | \n
|---|---|
ShellContent only | \nFlyoutItem > Tab > ShellContent | \n
Tab only | \nFlyoutItem > Tab | \n
ShellContent in TabBar | \nTabBar > Tab > ShellContent | \n
AppShell.xaml inheriting from ShellFlyoutItem or TabBar elements for top-level navigationTab elements for bottom tabs; nest multiple ShellContent for top tabsContentTemplate with DataTemplate so pages load on demandShellContent an explicit Route (see below)AppShell constructor\n\nSet
\nRoute=on everyShellContent. If you omit it, MAUI auto-generates a\nname from a shared counter —Routing.csproducesD_FAULT_{TypeName}{n}. A real\nshell with three unnamedShellContentelements yields routes like\nD_FAULT_ShellContent2andD_FAULT_ShellContent5: the numbers are not\nsequential, they depend on how many Shell elements were constructed first, and they\nshift when you reorder or add pages. You cannot write a stable absolute route\n(//dashboard) or deep link against that. An explicitRoute=\"dashboard\"is stable\nforever.
<Shell xmlns=\"http://schemas.microsoft.com/dotnet/2021/maui\"\n xmlns:x=\"http://schemas.microsoft.com/winfx/2009/xaml\"\n xmlns:views=\"clr-namespace:MyApp.Views\"\n x:Class=\"MyApp.AppShell\"\n FlyoutBehavior=\"Flyout\">\n\n <FlyoutItem Title=\"Animals\" Icon=\"animals.png\">\n <Tab Title=\"Cats\">\n <ShellContent Title=\"Domestic\" Route=\"domesticcats\"\n ContentTemplate=\"{DataTemplate views:DomesticCatsPage}\" />\n <ShellContent Title=\"Wild\" Route=\"wildcats\"\n ContentTemplate=\"{DataTemplate views:WildCatsPage}\" />\n </Tab>\n <Tab Title=\"Dogs\" Icon=\"dogs.png\">\n <ShellContent Route=\"dogs\" ContentTemplate=\"{DataTemplate views:DogsPage}\" />\n </Tab>\n </FlyoutItem>\n\n <TabBar>\n <ShellContent Title=\"Home\" Icon=\"home.png\" Route=\"home\"\n ContentTemplate=\"{DataTemplate views:HomePage}\" />\n <ShellContent Title=\"Settings\" Icon=\"settings.png\" Route=\"settings\"\n ContentTemplate=\"{DataTemplate views:SettingsPage}\" />\n </TabBar>\n</Shell>\n// AppShell.xaml.cs\npublic partial class AppShell : Shell\n{\n public AppShell()\n {\n InitializeComponent();\n Routing.RegisterRoute(\"animaldetails\", typeof(AnimalDetailsPage));\n Routing.RegisterRoute(\"editanimal\", typeof(EditAnimalPage));\n }\n}\nAll programmatic navigation uses Shell.Current.GoToAsync. Always await the call.
| Prefix | \nMeaning | \n
|---|---|
// | \nAbsolute route from Shell root | \n
| (none) | \nRelative; pushes onto the current nav stack | \n
.. | \nGo back one level | \n
../ | \nGo back then navigate forward | \n
// 1. Absolute — switch to a specific hierarchy location\nawait Shell.Current.GoToAsync(\"//animals/cats/domestic\");\n\n// 2. Relative — push a registered detail page\nawait Shell.Current.GoToAsync(\"animaldetails\");\n\n// 3. With query string parameters\nawait Shell.Current.GoToAsync($\"animaldetails?id={animal.Id}\");\n\n// 4. Go back one page\nawait Shell.Current.GoToAsync(\"..\");\n\n// 5. Go back two pages\nawait Shell.Current.GoToAsync(\"../..\");\n\n// 6. Go back one page, then push a different page\nawait Shell.Current.GoToAsync(\"../editanimal\");\nImplement on ViewModels to receive all parameters in one call:
\npublic class AnimalDetailsViewModel : ObservableObject, IQueryAttributable\n{\n public void ApplyQueryAttributes(IDictionary<string, object> query)\n {\n if (query.TryGetValue(\"id\", out var id))\n AnimalId = id.ToString();\n }\n}\nApply on the ViewModel class (or the page, if it genuinely owns the state).\nPrefer IQueryAttributable on the ViewModel — it keeps navigation state with the\nBindingContext and handles multiple parameters in one call:
[QueryProperty(nameof(AnimalId), \"id\")]\npublic partial class AnimalDetailsViewModel : ObservableObject\n{\n [ObservableProperty]\n private string _animalId = string.Empty;\n}\nShell applies query attributes after the page constructor sets BindingContext,\nso the property must raise change notification — a plain auto-property leaves the\nbinding stuck on its initial value.
Pass objects without serializing to strings:
\nvar parameters = new ShellNavigationQueryParameters\n{\n { \"animal\", selectedAnimal }\n};\nawait Shell.Current.GoToAsync(\"animaldetails\", parameters);\nReceive via IQueryAttributable:
public void ApplyQueryAttributes(IDictionary<string, object> query)\n{\n Animal = query[\"animal\"] as Animal;\n}\nUse GetDeferral() in OnNavigating for async checks (e.g., \"save unsaved changes?\"):
// In AppShell.xaml.cs\nprotected override async void OnNavigating(ShellNavigatingEventArgs args)\n{\n base.OnNavigating(args);\n if (hasUnsavedChanges && args.Source == ShellNavigationSource.Pop)\n {\n var deferral = args.GetDeferral();\n bool discard = await ShowConfirmationDialog();\n if (!discard)\n args.Cancel();\n deferral.Complete();\n }\n}\nMultiple ShellContent (or Tab) children inside a TabBar or FlyoutItem produce bottom tabs.
Multiple ShellContent children inside a single Tab produce top tabs:
<Tab Title=\"Photos\">\n <ShellContent Title=\"Recent\" ContentTemplate=\"{DataTemplate views:RecentPage}\" />\n <ShellContent Title=\"Favorites\" ContentTemplate=\"{DataTemplate views:FavoritesPage}\" />\n</Tab>\n| Attached Property | \nType | \nPurpose | \n
|---|---|---|
Shell.TabBarBackgroundColor | \nColor | \nTab bar background | \n
Shell.TabBarForegroundColor | \nColor | \nSelected icon color | \n
Shell.TabBarTitleColor | \nColor | \nSelected tab title color | \n
Shell.TabBarUnselectedColor | \nColor | \nUnselected tab icon/title | \n
Shell.TabBarIsVisible | \nbool | \nShow/hide the tab bar | \n
<!-- Hide the tab bar on a specific page -->\n<ContentPage Shell.TabBarIsVisible=\"False\" ... />\nSet on Shell: Disabled, Flyout, or Locked.
<Shell FlyoutBehavior=\"Flyout\"> ... </Shell>\nControls how children appear in the flyout:
\nAsSingleItem (default) — one flyout entry for the groupAsMultipleItems — each child Tab gets its own entry<FlyoutItem Title=\"Animals\" FlyoutDisplayOptions=\"AsMultipleItems\">\n <Tab Title=\"Cats\" ... />\n <Tab Title=\"Dogs\" ... />\n</FlyoutItem>\n<MenuItem Text=\"Log Out\"\n Command=\"{Binding LogOutCommand}\"\n IconImageSource=\"logout.png\" />\nCustomize the back button per page:
\n<Shell.BackButtonBehavior>\n <BackButtonBehavior Command=\"{Binding BackCommand}\"\n IconOverride=\"back_arrow.png\"\n TextOverride=\"Cancel\"\n IsVisible=\"True\" />\n</Shell.BackButtonBehavior>\nProperties: Command, CommandParameter, IconOverride, TextOverride, IsVisible, IsEnabled.
// Current URI location\nstring location = Shell.Current.CurrentState.Location.ToString();\n\n// Current page\nPage page = Shell.Current.CurrentPage;\n\n// Navigation stack of the current tab\nIReadOnlyList<Page> stack = Shell.Current.Navigation.NavigationStack;\nOverride in AppShell:
protected override void OnNavigated(ShellNavigatedEventArgs args)\n{\n base.OnNavigated(args);\n // args.Current, args.Previous, args.Source\n}\nShellNavigationSource values: Push, Pop, PopToRoot, Insert, Remove, ShellItemChanged, ShellSectionChanged, ShellContentChanged, Unknown.
Content directly instead of ContentTemplate with DataTemplate creates all pages at Shell init, hurting startup time. Always use ContentTemplate.Routing.RegisterRoute throws ArgumentException if a route name matches an existing route or a visual hierarchy route. Every route must be unique across the app.GoToAsync(\"somepage\") unless somepage was registered with Routing.RegisterRoute. Visual hierarchy pages use absolute // routes.GoToAsync causes race conditions and silent failures. Always await the call.//FlyoutItem/Tab/ShellContent). Wrong paths produce silent no-ops, not exceptions.GoToAsync for all navigation changes.GetDeferral() for async guards: Synchronous cancellation in OnNavigating works, but async checks require GetDeferral() / deferral.Complete() to avoid race conditions.references/shell-navigation-api.md — Full API reference for Shell hierarchy, routes, tabs, flyout, and navigation