Merge main into live

docs/fundamentals/shell/flyout.md

@@ -1,7 +1,7 @@
 ---
 title: ".NET MAUI Shell flyout"
 description: "Learn how to customize and control a .NET MAUI flyout, which is the optional root menu for a .NET MAUI Shell app."
-ms.date: 11/28/2025
+ms.date: 05/12/2026
 ---
 
 # .NET MAUI Shell flyout
@@ -771,6 +771,44 @@ The following example shows hiding an item in the flyout:
 > [!NOTE]
 > There's also a `Shell.FlyoutItemIsVisible` attached property, which can be set on <xref:Microsoft.Maui.Controls.FlyoutItem>,  <xref:Microsoft.Maui.Controls.MenuItem>, <xref:Microsoft.Maui.Controls.Tab>, and <xref:Microsoft.Maui.Controls.ShellContent> objects.
 
+:::moniker range=">=net-maui-11.0"
+
+## FlyoutItem badges
+
+A badge can be displayed on a flyout item to surface unread counts or status indicators. Badges are set on the Shell navigation item by using three bindable properties inherited from `BaseShellItem`:
+
+- `BadgeText`, of type `string`, is the text displayed on the badge. Set to a non-empty value to show a text or count badge, an empty string to show a dot indicator, or `null` (the default) to hide the badge.
+- `BadgeColor`, of type <xref:Microsoft.Maui.Graphics.Color>, is the background color of the badge. When `null`, the platform default is used.
+- `BadgeTextColor`, of type <xref:Microsoft.Maui.Graphics.Color>, is the foreground (text) color of the badge. When `null`, the platform default is used (typically white).
+
+The following example sets a numeric badge on a flyout item:
+
+```xaml
+<Shell ...>
+    <FlyoutItem Title="Inbox"
+                Icon="inbox.png"
+                BadgeText="3"
+                BadgeColor="Red"
+                BadgeTextColor="White">
+        <ShellContent ContentTemplate="{DataTemplate views:InboxPage}" />
+    </FlyoutItem>
+</Shell>
+```
+
+To bind the badge text to a view model, use a regular data binding:
+
+```xaml
+<FlyoutItem Title="Inbox"
+            Icon="inbox.png"
+            BadgeText="{Binding UnreadCount}">
+    <ShellContent ContentTemplate="{DataTemplate views:InboxPage}" />
+</FlyoutItem>
+```
+
+For more information on how badges are rendered on each platform, see [Tab badges](tabs.md#tab-badges).
+
+:::moniker-end
+
 ## Open and close the flyout programmatically
 
 The flyout can be programmatically opened and closed by setting the `Shell.FlyoutIsPresented` bindable property to a `boolean` value that indicates whether the flyout is currently open:

docs/fundamentals/shell/tabs.md

@@ -1,7 +1,7 @@
 ---
 title: ".NET MAUI Shell tabs"
 description: "Learn how to customize and control a .NET MAUI TabBar, which represents the bottom tab bar in a .NET MAUI Shell app."
-ms.date: 11/28/2025
+ms.date: 05/12/2026
 ---
 
 # .NET MAUI Shell tabs
@@ -282,3 +282,45 @@ In addition, <xref:Microsoft.Maui.Controls.Tab> objects can be hidden by setting
 ```
 
 In this example, the second tab is hidden.
+
+:::moniker range=">=net-maui-11.0"
+
+## Tab badges
+
+A badge can be displayed on a tab to surface unread counts or status indicators. Badges are set on the Shell navigation item (`Tab`, `ShellContent`, or `FlyoutItem`) by using three bindable properties inherited from `BaseShellItem`:
+
+- `BadgeText`, of type `string`, is the text displayed on the badge. Set to a non-empty value to show a text or count badge, an empty string to show a dot indicator, or `null` (the default) to hide the badge.
+- `BadgeColor`, of type <xref:Microsoft.Maui.Graphics.Color>, is the background color of the badge. When `null`, the platform default is used.
+- `BadgeTextColor`, of type <xref:Microsoft.Maui.Graphics.Color>, is the foreground (text) color of the badge. When `null`, the platform default is used (typically white).
+
+The following example sets a numeric badge on a tab:
+
+```xaml
+<TabBar>
+    <ShellContent Title="Inbox"
+                  Icon="inbox.png"
+                  BadgeText="3"
+                  BadgeColor="Red"
+                  BadgeTextColor="White"
+                  ContentTemplate="{DataTemplate views:InboxPage}" />
+    <ShellContent Title="Sent"
+                  Icon="sent.png"
+                  ContentTemplate="{DataTemplate views:SentPage}" />
+</TabBar>
+```
+
+To bind the badge text to a view model, use a regular data binding:
+
+```xaml
+<ShellContent Title="Inbox"
+              Icon="inbox.png"
+              BadgeText="{Binding UnreadCount}" />
+```
+
+Badge rendering varies by platform:
+
+- **Android** uses the Material Design `BadgeDrawable`. `BadgeTextColor` maps to `BadgeDrawable.BadgeTextColor`.
+- **iOS and Mac Catalyst** use `UITabBarItem.BadgeValue`. `BadgeTextColor` maps to `UITabBarItem.SetBadgeTextAttributes`.
+- **Windows** uses the WinUI `InfoBadge` control. Only numeric `BadgeText` values display as a count; non-numeric text and the empty string display as a dot indicator. `BadgeTextColor` maps to `InfoBadge.Foreground`.
+
+:::moniker-end

docs/user-interface/controls/editor.md

@@ -1,7 +1,7 @@
 ---
 title: "Editor"
 description: "The .NET MAUI Editor allows you to enter and edit multiple lines of text."
-ms.date: 05/13/2025
+ms.date: 05/12/2026
 ---
 
 # Editor
@@ -18,6 +18,12 @@ These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> o
 
 In addition, <xref:Microsoft.Maui.Controls.Editor> defines a `Completed` event, which is raised when the user finalizes text in the <xref:Microsoft.Maui.Controls.Editor> with the return key.
 
+:::moniker range=">=net-maui-11.0"
+
+<xref:Microsoft.Maui.Controls.Editor> also defines `ReturnCommand` and `ReturnCommandParameter` properties, both of which are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects. `ReturnCommand`, of type <xref:System.Windows.Input.ICommand>, is executed whenever the `Completed` event is raised. `ReturnCommandParameter`, of type `object`, is passed to `ReturnCommand` when it's executed. This lets you bind a view model command directly to the editor's completion gesture without subscribing to the `Completed` event in code-behind.
+
+:::moniker-end
+
 <xref:Microsoft.Maui.Controls.Editor> derives from the <xref:Microsoft.Maui.Controls.InputView> class, from which it inherits the following properties:
 
 - `CharacterSpacing`, of type `double`, sets the spacing between characters in the text content, including both the user-entered or displayed text and the placeholder text.
@@ -114,6 +120,18 @@ void OnEditorCompleted(object sender, EventArgs e)
 }
 ```
 
+:::moniker range=">=net-maui-11.0"
+
+Alternatively, you can bind a command to the editor's completion gesture by setting `ReturnCommand` and, optionally, `ReturnCommandParameter`. The command is invoked whenever the `Completed` event is raised:
+
+```xaml
+<Editor Text="{Binding Note}"
+        ReturnCommand="{Binding SaveNoteCommand}"
+        ReturnCommandParameter="{Binding Note}" />
+```
+
+:::moniker-end
+
 ## Set character spacing
 
 Character spacing can be applied to an <xref:Microsoft.Maui.Controls.Editor> by setting the `CharacterSpacing` property to a `double` value:

docs/user-interface/images/app-icons.md

@@ -1,7 +1,7 @@
 ---
 title: "Add an app icon to a .NET MAUI app project"
 description: "Learn how to add an app icon to a .NET MAUI app project. The icon is the logo that represents your app in multiple places, such as the Store, launcher, or app shortcut."
-ms.date: 08/30/2024
+ms.date: 05/12/2026
 no-loc: ["MauiIcon"]
 ---
 
@@ -188,6 +188,28 @@ Adaptive launcher icons are composed icons, using a background layer and a foreg
 
 The `ForegroundScale` attribute can be optionally specified to rescale the foreground image so that it fits on the app icon. It's a percentage value so 0.65 will be translated as 65%.
 
+:::moniker range=">=net-maui-11.0"
+
+#### Themed icon monochrome layer
+
+On Android 13 and higher, the system can render a themed app icon that uses a single monochrome glyph tinted with colors derived from the user's wallpaper. By default, .NET MAUI uses the `ForegroundFile` image as the monochrome layer. To use a different glyph for the themed icon, specify the `MonochromeFile` attribute on the `<MauiIcon>` item:
+
+```xml
+<ItemGroup>
+    <MauiIcon Include="Resources\AppIcon\appicon.svg"
+              ForegroundFile="Resources\AppIcon\appiconfg.svg"
+              MonochromeFile="Resources\AppIcon\appiconmono.svg"
+              ForegroundScale="0.65"
+              Color="#512BD4" />
+</ItemGroup>
+```
+
+The `MonochromeFile` image should be a single-color glyph designed to read clearly when tinted by the system. The image is included in the generated adaptive icon as the `<monochrome>` layer of the `adaptive-icon` drawable. If `MonochromeFile` isn't specified, the foreground image continues to be used as the monochrome source.
+
+For more information about themed icons on Android, see [Adaptive icons](https://developer.android.com/develop/ui/views/launch/icon_design_adaptive) and [Support themed app icons](https://developer.android.com/about/versions/13/features#themed-app-icons) on developer.android.com.
+
+:::moniker-end
+
 # [iOS/Mac Catalyst](#tab/macios)
 
 The app icon defined by your .NET MAUI app is used to generate an asset catalog icon set for both iOS and macOS platforms. The name of the icon set is defined in the _Info.plist_ file, which on iOS is located at _Platforms\\iOS\\Info.plist_. For macOS, the _Info.plist_ file is located at _Platforms\\MacCatalyst\\Info.plist_.

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: 04/13/2026
+ms.date: 05/12/2026
 ---
 
 # Material 3
@@ -257,6 +257,28 @@ The following screenshot shows the difference between Material 2 and Material 3.
 
 For more information about the underlying Android component, see [MaterialDatePicker](https://developer.android.com/reference/com/google/android/material/datepicker/MaterialDatePicker).
 
+:::moniker range=">=net-maui-11.0"
+
+### ImageButton
+
+The [ImageButton](controls/imagebutton.md) control on Android is rendered using the Material 3 `ShapeableImageView` when the feature is enabled, picking up Material 3 shape, ripple, and elevation behaviors that match other Material 3 buttons.
+
+For more information about the underlying Android control, see [ShapeableImageView](https://developer.android.com/reference/com/google/android/material/imageview/ShapeableImageView).
+
+### Switch
+
+The [Switch](controls/switch.md) control on Android is rendered using the Material 3 `MaterialSwitch` when the feature is enabled, replacing the legacy `SwitchCompat` track and thumb with the updated Material 3 design.
+
+For more information about the underlying Android control, see [MaterialSwitch](https://developer.android.com/reference/com/google/android/material/materialswitch/MaterialSwitch).
+
+### Shell
+
+When the feature is enabled, the [Shell](~/fundamentals/shell/index.md) tab bar on Android is rendered using the Material 3 navigation components. Bottom tabs use the Material 3 `NavigationBar` and top tabs use the Material 3 `TabLayout`, both of which adopt Material 3 color tokens, shape, and selection states. Tab badges set with `BadgeText`, `BadgeColor`, and `BadgeTextColor` are rendered through the Material 3 `BadgeDrawable`.
+
+For more information about the underlying Android controls, see [NavigationBar](https://developer.android.com/reference/com/google/android/material/navigation/NavigationBar) and [TabLayout](https://developer.android.com/reference/com/google/android/material/tabs/TabLayout).
+
+:::moniker-end
+
 ## Considerations
 
 When enabling Material 3 in your .NET MAUI Android app, consider the following:

docs/user-interface/toolbaritem.md

@@ -1,7 +1,7 @@
 ---
 title: "Display toolbar items"
 description: "Learn how to add toolbar items, which are a special type of button, to the app's navigation bar."
-ms.date: 08/18/2025
+ms.date: 05/12/2026
 ---
 
 # Display toolbar items
@@ -147,3 +147,43 @@ On iOS and Mac Catalyst, secondary items are shown in a pull‑down menu ordered
 > Keep labels short so they fit comfortably in the pull‑down. Avoid icons for `Secondary` items due to platform inconsistency.
 
 ::: moniker-end
+
+:::moniker range=">=net-maui-11.0"
+
+## Display a badge on a ToolbarItem
+
+A badge can be displayed on a <xref:Microsoft.Maui.Controls.ToolbarItem> to surface counts or status indicators. The `ToolbarItem` class defines three bindable properties for badge support:
+
+- `BadgeText`, of type `string`, is the text displayed on the badge. Set to a non-empty value to show a text or count badge, an empty string to show a dot indicator, or `null` (the default) to hide the badge.
+- `BadgeColor`, of type <xref:Microsoft.Maui.Graphics.Color>, is the background color of the badge. When `null`, the platform default is used.
+- `BadgeTextColor`, of type <xref:Microsoft.Maui.Graphics.Color>, is the foreground (text) color of the badge. When `null`, the platform default is used.
+
+The following example sets a numeric badge on a toolbar item:
+
+```xaml
+<ContentPage.ToolbarItems>
+    <ToolbarItem Text="Inbox"
+                 IconImageSource="inbox.png"
+                 BadgeText="3"
+                 BadgeColor="Red"
+                 BadgeTextColor="White" />
+</ContentPage.ToolbarItems>
+```
+
+To bind the badge text to a view model, use a regular data binding:
+
+```xaml
+<ToolbarItem Text="Inbox"
+             IconImageSource="inbox.png"
+             BadgeText="{Binding UnreadCount}" />
+```
+
+Badges are only displayed on primary toolbar items — items whose <xref:Microsoft.Maui.Controls.ToolbarItem.Order> is set to <xref:Microsoft.Maui.Controls.ToolbarItemOrder.Primary> or <xref:Microsoft.Maui.Controls.ToolbarItemOrder.Default>. Secondary (overflow) items don't display badges.
+
+Badge rendering varies by platform:
+
+- **Android** uses the Material Design `BadgeDrawable`. Numeric and text badges are supported. `BadgeTextColor` maps to `BadgeDrawable.BadgeTextColor`.
+- **iOS and Mac Catalyst** use `UIBarButtonItem.Badge`, which requires iOS 26 or higher. On earlier iOS versions, the badge is silently ignored. `BadgeTextColor` maps to `UIBarButtonItemBadge.ForegroundColor`.
+- **Windows** uses the WinUI `InfoBadge` overlaid on the toolbar button. Numeric values display as counts; non-numeric text and the empty string display as a dot indicator. `BadgeTextColor` maps to `InfoBadge.Foreground`.
+
+:::moniker-end