Skip to content

Clarify TabbedPage Shell incompatibility and modal usage #3117

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Clarify TabbedPage Shell incompatibility and modal usage #3117

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a6421ad
Initial plan
Copilot Nov 28, 2025
1464910
Clarify TabbedPage Shell incompatibility with specific navigation sce…
Copilot Nov 28, 2025
896349d
Clarify that TabbedPage can be used as a modal in Shell apps
Copilot Dec 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/user-interface/pages/tabbedpage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "TabbedPage"
description: "The .NET MAUI TabbedPage consists of a series of pages that are navigable by tabs across the top or bottom of the page, with each tab loading the page content."
ms.date: 09/30/2024
ms.date: 11/28/2025
---

# TabbedPage
Expand All @@ -25,7 +25,7 @@ The title of a tab is defined by the <xref:Microsoft.Maui.Controls.Page.Title?di
In a <xref:Microsoft.Maui.Controls.TabbedPage>, each <xref:Microsoft.Maui.Controls.Page> object is created when the <xref:Microsoft.Maui.Controls.TabbedPage> is constructed. This can lead to a poor user experience, particularly if the <xref:Microsoft.Maui.Controls.TabbedPage> is the root page of your app. However, .NET MAUI Shell enables pages accessed through a tab bar to be created on demand, in response to navigation. For more information about Shell apps, see [Shell](~/fundamentals/shell/index.md).

> [!WARNING]
> <xref:Microsoft.Maui.Controls.TabbedPage> is incompatible with .NET MAUI Shell apps, and an exception will be thrown if you attempt to use <xref:Microsoft.Maui.Controls.TabbedPage> in a Shell app.
> <xref:Microsoft.Maui.Controls.TabbedPage> is incompatible with the .NET MAUI Shell visual hierarchy, and an exception will be thrown if you attempt to add <xref:Microsoft.Maui.Controls.TabbedPage> to the Shell visual hierarchy. This includes registering a <xref:Microsoft.Maui.Controls.TabbedPage> as a route with `Routing.RegisterRoute` and navigating to it with `Shell.Current.GoToAsync`. However, it's valid to display a <xref:Microsoft.Maui.Controls.TabbedPage> as a modal page in a Shell app by using `Navigation.PushModalAsync`, because modal pages exist in a separate navigation space. If you need tab-based navigation as part of the Shell visual hierarchy, use Shell tabs instead. For more information, see [Shell tabs](~/fundamentals/shell/tabs.md) and [Perform modal navigation](~/user-interface/pages/navigationpage.md#perform-modal-navigation).

## Create a TabbedPage

Expand Down