Shell (.NET 11): document Android handler architecture

docs/fundamentals/shell/index.md

@@ -1,7 +1,7 @@
 ---
 title: ".NET MAUI Shell overview"
 description: ".NET MAUI Shell provides the fundamental features that most apps require, including a common navigation user experience, a URI-based navigation scheme, and an integrated search handler."
-ms.date: 08/30/2024
+ms.date: 07/08/2026
 ---
 
 # .NET MAUI Shell overview
@@ -30,6 +30,27 @@ These objects don't represent any user interface, but rather the organization of
 
 For more information, see [Create a .NET MAUI Shell app](create.md).
 
+::: moniker range=">=net-maui-11.0"
+
+## Android handler architecture
+
+Starting in .NET MAUI 11, Shell on Android uses a handler-based architecture by default. The Android implementation is built around `ShellHandler`, `ShellItemHandler`, and `ShellSectionHandler`, and reuses `MauiDrawerLayout`, `TabbedViewManager`, and the navigation handler infrastructure used by other .NET MAUI navigation controls. This doesn't change how you define the Shell hierarchy in XAML or C#.
+
+iOS and Mac Catalyst Shell continue to use the legacy `ShellRenderer`. If an Android app depends on legacy Shell renderer behavior or custom Android `ShellRenderer` subclasses, you can opt out of the Android handler architecture by registering the compatibility renderer explicitly:
+
+```csharp
+builder.ConfigureMauiHandlers(handlers =>
+{
+#if ANDROID
+    handlers.AddHandler<Shell, Microsoft.Maui.Controls.Handlers.Compatibility.ShellRenderer>();
+#endif
+});
+```
+
+For custom Android Shell renderer migration guidance, see [Reuse custom renderers in .NET MAUI](~/migration/custom-renderers.md#migrate-android-shell-renderers).
+
+::: moniker-end
+
 ## Navigation user experience
 
 The navigation experience provided by .NET MAUI Shell is based on flyouts and tabs. The top level of navigation in a Shell app is either a flyout or a bottom tab bar, depending on the navigation requirements of the app. The following example shows an app where the top level of navigation is a flyout:

docs/migration/custom-renderers.md

@@ -1,7 +1,7 @@
 ---
 title: "Reuse custom renderers in .NET MAUI"
 description: "Learn how to adapt Xamarin.Forms custom renderers to work in a .NET MAUI app."
-ms.date: 04/13/2023
+ms.date: 07/08/2026
 ---
 
 # Reuse custom renderers in .NET MAUI
@@ -84,6 +84,34 @@ The renderers are registered with the <xref:Microsoft.Maui.Hosting.HandlerMauiAp
 > [!IMPORTANT]
 > Only renderers that derive from `FrameRenderer`, `ListViewRenderer`, `NavigationRenderer` on iOS, `ShellRenderer` on iOS and Android, `TabbedRenderer` on iOS, `TableViewRenderer`, and `VisualElementRenderer` can be registered with the <xref:Microsoft.Maui.Hosting.MauiHandlersCollectionExtensions.AddHandler%2A> method.
 
+::: moniker range=">=net-maui-11.0"
+
+### Migrate Android Shell renderers
+
+Starting in .NET MAUI 11, Android Shell uses handlers by default. Apps with custom Android Shell renderer subclasses should migrate those customizations to the Android Shell handler types where possible:
+
+| Android renderer customization | Handler customization |
+| -- | -- |
+| `ShellRenderer` subclass | `ShellHandler` subclass |
+| `ShellItemRenderer` subclass | `ShellItemHandler` subclass |
+| `ShellSectionRenderer` subclass | `ShellSectionHandler` subclass |
+| `ShellItemRenderer.OnTabReselected()` | `ShellItemHandler.OnTabReselected()` |
+| Shell `More` overflow menu or bottom sheet customization | `ShellItemHandler.CreateMoreBottomSheet()` |
+| Navigation animation `SetupAnimation(...)` | `ShellSectionHandler.OnCreateNavigationAnimation(Context, bool isPopping, bool enter)` |
+
+If you need the legacy Android Shell renderer while migrating, register it explicitly with <xref:Microsoft.Maui.Hosting.HandlerMauiAppBuilderExtensions.ConfigureMauiHandlers%2A>:
+
+```csharp
+builder.ConfigureMauiHandlers(handlers =>
+{
+#if ANDROID
+    handlers.AddHandler<Shell, Microsoft.Maui.Controls.Handlers.Compatibility.ShellRenderer>();
+#endif
+});
+```
+
+::: moniker-end
+
 ### Consume the custom renderers
 
 The custom renderer can be consumed in a .NET MAUI app as a custom control:

docs/user-interface/handlers/index.md

@@ -1,7 +1,7 @@
 ---
 title: ".NET MAUI handlers"
 description: "Learn about .NET MAUI handlers, which map cross-platform controls to performant native controls on each platform."
-ms.date: 01/13/2025
+ms.date: 07/08/2026
 ---
 
 # Handlers
@@ -97,19 +97,38 @@ The following table lists the types that implement views in .NET MAUI:
 
 The following table lists the types that implement pages in .NET MAUI:
 
+::: moniker range="<=net-maui-10.0"
+
 | Page | Android Handler | iOS/Mac Catalyst Handler | Windows Handler | Property Mapper | Command Mapper |
 | -- | -- | -- | -- | -- | -- |
 | <xref:Microsoft.Maui.Controls.ContentPage> | <xref:Microsoft.Maui.Handlers.PageHandler> | <xref:Microsoft.Maui.Handlers.PageHandler> | <xref:Microsoft.Maui.Handlers.PageHandler> | <xref:Microsoft.Maui.Handlers.PageHandler.Mapper> | <xref:Microsoft.Maui.Handlers.PageHandler.CommandMapper> |
 | <xref:Microsoft.Maui.Controls.FlyoutPage> | <xref:Microsoft.Maui.Handlers.FlyoutViewHandler> | PhoneFlyoutPageRenderer | <xref:Microsoft.Maui.Handlers.FlyoutViewHandler> | `Mapper` | <xref:Microsoft.Maui.CommandMapper> |
 | <xref:Microsoft.Maui.Controls.NavigationPage> | <xref:Microsoft.Maui.Handlers.NavigationViewHandler> | NavigationRenderer | <xref:Microsoft.Maui.Handlers.NavigationViewHandler> | `Mapper` | <xref:Microsoft.Maui.CommandMapper> |
 | <xref:Microsoft.Maui.Controls.TabbedPage> | <xref:Microsoft.Maui.Handlers.TabbedViewHandler> | TabbedRenderer | <xref:Microsoft.Maui.Handlers.TabbedViewHandler> | `Mapper` | <xref:Microsoft.Maui.CommandMapper> |
-| <xref:Microsoft.Maui.Controls.Shell> | `ShellHandler` | ShellRenderer | ShellRenderer | `Mapper` | <xref:Microsoft.Maui.CommandMapper> |
+| <xref:Microsoft.Maui.Controls.Shell> | ShellRenderer | ShellRenderer | `ShellHandler` | `Mapper` | <xref:Microsoft.Maui.CommandMapper> |
+
+::: moniker-end
+
+::: moniker range=">=net-maui-11.0"
+
+| Page | Android Handler | iOS/Mac Catalyst Handler | Windows Handler | Property Mapper | Command Mapper |
+| -- | -- | -- | -- | -- | -- |
+| <xref:Microsoft.Maui.Controls.ContentPage> | <xref:Microsoft.Maui.Handlers.PageHandler> | <xref:Microsoft.Maui.Handlers.PageHandler> | <xref:Microsoft.Maui.Handlers.PageHandler> | <xref:Microsoft.Maui.Handlers.PageHandler.Mapper> | <xref:Microsoft.Maui.Handlers.PageHandler.CommandMapper> |
+| <xref:Microsoft.Maui.Controls.FlyoutPage> | <xref:Microsoft.Maui.Handlers.FlyoutViewHandler> | PhoneFlyoutPageRenderer | <xref:Microsoft.Maui.Handlers.FlyoutViewHandler> | `Mapper` | <xref:Microsoft.Maui.CommandMapper> |
+| <xref:Microsoft.Maui.Controls.NavigationPage> | <xref:Microsoft.Maui.Handlers.NavigationViewHandler> | NavigationRenderer | <xref:Microsoft.Maui.Handlers.NavigationViewHandler> | `Mapper` | <xref:Microsoft.Maui.CommandMapper> |
+| <xref:Microsoft.Maui.Controls.TabbedPage> | <xref:Microsoft.Maui.Handlers.TabbedViewHandler> | TabbedRenderer | <xref:Microsoft.Maui.Handlers.TabbedViewHandler> | `Mapper` | <xref:Microsoft.Maui.CommandMapper> |
+| <xref:Microsoft.Maui.Controls.Shell> | `ShellHandler` | ShellRenderer | `ShellHandler` | `Mapper` | <xref:Microsoft.Maui.CommandMapper> |
+
+> [!NOTE]
+> Starting in .NET MAUI 11, Android Shell uses the handler-based `ShellHandler`, `ShellItemHandler`, and `ShellSectionHandler` by default. iOS and Mac Catalyst Shell continue to use `ShellRenderer`.
+
+::: moniker-end
 
 <!--
 xrefs not used on:
 
 1. Mapper and CommandMapper because the properties are in different files (handlers vs compatibility renderers).
 1. Renderer classes because they are platform-specific, and the API docs only exist for the xplat layer.
-1. No API doc for ShellHandler.
+1. No API doc for ShellHandler, ShellItemHandler, or ShellSectionHandler.
 
 -->