Document public Material 3 helper types in .NET MAUI 11

docs/user-interface/material-design.md

@@ -1,7 +1,7 @@
 ---
 title: "Material 3"
 description: "Learn how to enable Material 3 design on Android in .NET MAUI apps by setting the UseMaterial3 build property to apply modern Material Design theming and components."
-ms.date: 05/12/2026
+ms.date: 06/05/2026
 ---
 
 # Material 3
@@ -279,6 +279,71 @@ For more information about the underlying Android controls, see [BottomNavigatio
 
 :::moniker-end
 
+:::moniker range=">=net-maui-11.0"
+
+## Customize Material 3 controls
+
+Starting in .NET MAUI 11, the Material 3 helper types in the `Microsoft.Maui.Platform` namespace are public, so you can subclass them and supply your own variants from a [custom handler](handlers/index.md). Use this when the default Material 3 rendering is close to what you need but you want to override a specific behavior—for example, intercepting touch events, customizing measurement, or applying a custom theme wrapper—without re-implementing the full Material 3 integration.
+
+The following helper types are public. When `UseMaterial3` is `true`, MAUI swaps to the "`Handler2`" variant of the corresponding control's handler, whose platform view type is the Material 3 helper:
+
+| Type | Used as the platform view by |
+|---|---|
+| `Microsoft.Maui.Platform.MauiMaterialEditText` | `Microsoft.Maui.Handlers.EditorHandler2` |
+| `Microsoft.Maui.Platform.MauiMaterialPicker` | `Microsoft.Maui.Handlers.PickerHandler2` |
+| `Microsoft.Maui.Platform.MauiMaterialDatePicker` | `Microsoft.Maui.Handlers.DatePickerHandler2` |
+| `Microsoft.Maui.Platform.MauiMaterialTimePicker` | `Microsoft.Maui.Handlers.TimePickerHandler2` |
+| `Microsoft.Maui.Platform.MauiMaterialSearchBarTextInputLayout` | `Microsoft.Maui.Handlers.SearchBarHandler2` (wraps the search input) |
+| `Microsoft.Maui.Platform.MauiMaterialTextView` | Internal Material 3 <xref:Microsoft.Maui.Controls.Label> rendering. |
+| `Microsoft.Maui.Platform.MaterialActivityIndicator` | Internal Material 3 <xref:Microsoft.Maui.Controls.ActivityIndicator> rendering. |
+| `Microsoft.Maui.Platform.MauiMaterialContextThemeWrapper` | A Material 3 `ContextThemeWrapper` you can build with `MauiMaterialContextThemeWrapper.Create(context)` for your own custom platform views. |
+
+For the types that are direct platform views of a `Handler2` variant, you can swap them by setting the handler's `PlatformViewFactory`. The factory **replaces** the handler's default `CreatePlatformView` method, so it must apply any default Material 3 theming and control-specific setup that the handler would otherwise perform. The following example shows how to do this for <xref:Microsoft.Maui.Controls.Editor>:
+
+```csharp
+#if ANDROID
+using Android.Views;
+using Android.Views.InputMethods;
+using Microsoft.Maui.Handlers;
+using Microsoft.Maui.Platform;
+
+internal sealed class MyMaterialEditText : MauiMaterialEditText
+{
+    public MyMaterialEditText(Android.Content.Context context) : base(context)
+    {
+    }
+
+    protected override bool OnTouchEvent(MotionEvent? e)
+    {
+        // Custom touch handling. Delegate to the base when finished.
+        return base.OnTouchEvent(e);
+    }
+}
+
+EditorHandler2.PlatformViewFactory = handler =>
+{
+    // Wrap the context in the Material 3 theme overlay, then apply the
+    // same Editor-specific setup that EditorHandler2.CreatePlatformView
+    // performs by default.
+    var view = new MyMaterialEditText(MauiMaterialContextThemeWrapper.Create(handler.Context!))
+    {
+        ImeOptions = ImeAction.Done,
+        Gravity = GravityFlags.Top,
+        TextAlignment = global::Android.Views.TextAlignment.ViewStart,
+    };
+    view.SetSingleLine(false);
+    view.SetHorizontallyScrolling(false);
+    return view;
+};
+#endif
+```
+
+When `UseMaterial3` is `true`, `EditorHandler2` creates your `MyMaterialEditText` subclass instead of the default `MauiMaterialEditText`, and the Material 3 theme overlay and multi-line behavior continue to apply.
+
+For more information about handler customization, see [Customize controls with handlers](handlers/customize.md).
+
+:::moniker-end
+
 ## Considerations
 
 When enabling Material 3 in your .NET MAUI Android app, consider the following: