diff --git a/docs/user-interface/material-design.md b/docs/user-interface/material-design.md index f1dca306f4..a3dc5cb824 100644 --- a/docs/user-interface/material-design.md +++ b/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 rendering. | +| `Microsoft.Maui.Platform.MaterialActivityIndicator` | Internal Material 3 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 : + +```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: