Clarify TabbedPage Shell incompatibility and modal usage

[Copilot]

Users attempting to navigate to a TabbedPage from a Shell app using Routing.RegisterRoute and Shell.Current.GoToAsync get a "View Not found" error with no clear explanation why.

Changes

• Expanded the existing Shell incompatibility WARNING to explicitly mention:
  • Routing.RegisterRoute cannot register a TabbedPage as a route in the Shell visual hierarchy
  • Shell.Current.GoToAsync cannot navigate to a TabbedPage
  • TabbedPage CAN be used as a modal page in Shell apps using Navigation.PushModalAsync because modal pages exist in a separate navigation space
• Added links to:
  • Shell tabs documentation as the recommended alternative for tab-based navigation in the Shell visual hierarchy
  • Modal navigation documentation for displaying TabbedPage modally in Shell apps

Example of what doesn't work

// This fails - TabbedPage cannot be used with Shell navigation hierarchy
Routing.RegisterRoute("CustomTabPage", typeof(CustomTabPage)); // CustomTabPage : TabbedPage
await Shell.Current.GoToAsync(nameof(CustomTabPage)); // "View Not found"

Example of what DOES work

// This works - TabbedPage can be displayed as a modal
await Navigation.PushModalAsync(new CustomTabPage()); // CustomTabPage : TabbedPage

For Shell apps needing tabs as part of the visual hierarchy, use TabBar/Tab/ShellContent instead. For displaying a TabbedPage temporarily, use modal navigation.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Navigating Tabbed Page creating Issue</issue_title>
<issue_description>### Type of issue

Code doesn't work

Description

I have created TabbedPage in MAUI ,

"

<ContentPage Title="Tab 1">
    <StackLayout>
        <Label Text="This is Tab 1" />
    </StackLayout>
</ContentPage>
<ContentPage Title="Tab 2">
    <StackLayout>
        <Label Text="This is Tab 2" />
    </StackLayout>
</ContentPage>

"

In AppShell.Xaml.Cs registered Rout

Routing.RegisterRoute("CustomTabPage", typeof(CustomTabPage));

On MainPage.Xaml.cs I am calling TabbedPage as
private async void OnProceedClicked(object sender, EventArgs e)
{

await Shell.Current.GoToAsync(nameof(CustomTabPage));          

}

I am getting error as "View Not found"

Will someone help in this regards

If calling with Navigation.PushModalAsync(new NavigationPage( ...)..
The Back Button is not visible in TabbedPage
[Enter feedback here]

Page URL

https://learn.microsoft.com/en-us/dotnet/maui/user-interface/pages/tabbedpage?view=net-maui-8.0

Content source URL

https://github.com/dotnet/docs-maui/blob/main/docs/user-interface/pages/tabbedpage.md

Document Version Independent Id

d9f1977c-bc41-c096-0b17-6db418d440b0

Article author

@davidbritch

Metadata

• ID: d9f1977c-bc41-c096-0b17-6db418d440b0
• Service: dotnet-mobile
• Sub-service: dotnet-maui</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Navigating Tabbed Page creating Issue #2389

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[learn-build-service-prod]

Learn Build status updates of commit a6421ad:

✅ Validation status: passed

For more details, please refer to the build report.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 1464910:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/user-interface/pages/tabbedpage.md	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

[PureWeen]

@copilot this should clarify that for modals you can register tabbedpage, flyoutpage and navigationpage because its a separate space from shell

[Copilot]

@copilot this should clarify that for modals you can register tabbedpage, flyoutpage and navigationpage because its a separate space from shell

Updated in 896349d. The warning now clarifies that TabbedPage is incompatible with the Shell visual hierarchy specifically, but can be displayed as a modal page using Navigation.PushModalAsync since modal pages exist in a separate navigation space. Added link to the modal navigation documentation.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 896349d:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/user-interface/pages/tabbedpage.md	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.