Add Shell badge support (BadgeText, BadgeColor, BadgeTextColor) by jfversluis · Pull Request #34659 · dotnet/maui

jfversluis · 2026-03-25T22:40:25Z

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Description

Adds badge notification support to Shell bottom tabs on all platforms (Android, iOS, MacCatalyst, Windows).

Closes #8305 (first iteration — bottom tabs)

New API

Three new bindable properties on BaseShellItem:

Property	Type	Description
`BadgeText`	`string?`	Text/number displayed on the badge. `null` = no badge, `""` = dot indicator, non-empty = text/count badge.
`BadgeColor`	`Color?`	Background color of the badge. `null` uses the platform default.
`BadgeTextColor`	`Color?`	Foreground (text) color of the badge. `null` uses the platform default (typically white).

XAML Usage

<Shell>
    <TabBar>
        <ShellContent Title="Home" BadgeText="3" BadgeColor="Red" BadgeTextColor="White" />
        <ShellContent Title="Alerts" BadgeText="" /> <!-- dot indicator -->
    </TabBar>
</Shell>

Platform Implementation

Platform	Approach	Notes
Android	`BottomNavigationView.GetOrCreateBadge()` / `BadgeDrawable`	Full text + color support. `ClearNumber()` for dot mode.
iOS/MacCatalyst	`UITabBarItem.BadgeValue` / `BadgeColor` / `SetBadgeTextAttributes`	Full text + color support. Empty string shows native dot.
Windows	`InfoBadge` on `NavigationViewItem` via ViewModel binding	Numeric values show number; non-numeric/empty shows dot indicator.

Dot Badge Support

Setting BadgeText = "" (empty string) displays a small dot indicator without text on all platforms. This is distinct from null which hides the badge entirely.

What's Included

3 BindableProperties on BaseShellItem with full XML documentation
Platform handlers for Android, iOS/MacCatalyst, and Windows
28 unit tests (ShellBadgeTests.cs)
4 UI screenshot tests (Issue8305.cs)
Interactive sample gallery page (ShellBadgeGallery)
PublicAPI.Unshipped.txt entries for all 7 TFMs

What's NOT Included (follow-up work)

Flyout item badges
Top tab badges
These are tracked in the original issue Add Shell Badge support #8305 for future iterations

Screenshots

Testing

All 28 unit tests pass
All 85 existing Shell unit tests pass (no regression)
UI test projects compile successfully
Manually tested on physical Android device

github-actions · 2026-03-25T22:40:35Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 34659

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 34659"

Add BadgeText and BadgeColor bindable properties to BaseShellItem, enabling badge indicators on Shell bottom tab items across all platforms. Platform implementations: - Android: BadgeDrawable on BottomNavigationView with text and color support - iOS/MacCatalyst: UITabBarItem.BadgeValue and BadgeColor - Windows: InfoBadge on NavigationViewItem with ViewModel binding Includes 19 unit tests and interactive sample page. Fixes #8305 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add HostApp test page (Issue8305) with Shell tabs and badge controls - Add 4 NUnit UI tests: initial badge, runtime set, clear, multiple tabs - Fix missing using directives in ShellBadgeGallery sample page Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Adds Shell badge support (text + background color) for bottom tabs across platforms, wiring new BaseShellItem bindable properties through platform renderers/handlers and adding test/sample coverage.

Changes:

Introduces BadgeText / BadgeColor bindable properties on BaseShellItem.
Implements badge rendering updates for Android (BottomNavigationView), iOS/MacCatalyst (UITabBarItem), and Windows (InfoBadge via NavigationViewItem).
Adds unit tests, UI screenshot tests, and a sample gallery page demonstrating badge behavior.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/Core/src/Platform/Windows/NavigationViewItemViewModel.cs	Adds badge-related view-model properties for WinUI binding (text, background, computed visibility/value).
src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue8305.cs	Adds UI screenshot tests for initial/runtime/cleared/multiple badge states.
src/Controls/tests/TestCases.HostApp/Issues/Issue8305.cs	Adds HostApp test page for interactive badge updates via buttons.
src/Controls/tests/Core.UnitTests/ShellBadgeTests.cs	Adds unit tests validating defaults, binding, and property change behavior for badge properties.
src/Controls/src/Core/Shell/BaseShellItem.cs	Adds the new bindable properties and public API surface on `BaseShellItem`.
src/Controls/src/Core/PublicAPI/netstandard/PublicAPI.Unshipped.txt	Records new badge APIs for netstandard.
src/Controls/src/Core/PublicAPI/net/PublicAPI.Unshipped.txt	Records new badge APIs for .NET.
src/Controls/src/Core/PublicAPI/net-windows/PublicAPI.Unshipped.txt	Records new badge APIs for Windows TFM.
src/Controls/src/Core/PublicAPI/net-tizen/PublicAPI.Unshipped.txt	Records new badge APIs for Tizen TFM.
src/Controls/src/Core/PublicAPI/net-maccatalyst/PublicAPI.Unshipped.txt	Records new badge APIs for MacCatalyst TFM.
src/Controls/src/Core/PublicAPI/net-ios/PublicAPI.Unshipped.txt	Records new badge APIs for iOS TFM.
src/Controls/src/Core/PublicAPI/net-android/PublicAPI.Unshipped.txt	Records new badge APIs for Android TFM (also includes new protected virtual renderer method).
src/Controls/src/Core/Platform/Windows/TabbedPage/TabbedPageStyle.xaml	Wires WinUI `InfoBadge` into the tab template via bindings.
src/Controls/src/Core/Handlers/Shell/ShellItemHandler.Windows.cs	Maps badge properties to Windows tab view-model and tracks runtime updates.
src/Controls/src/Core/Compatibility/Handlers/Shell/iOS/ShellItemRenderer.cs	Updates UITabBarItem badge text/color on initial setup and on property changes.
src/Controls/src/Core/Compatibility/Handlers/Shell/Android/ShellItemRenderer.cs	Implements Android badge creation/removal and updates on property changes/menu setup.
src/Controls/samples/Controls.Sample/Pages/Core/ShellGalleries/ShellBadgeGallery.cs	Adds an interactive sample page for setting/clearing badges and colors.
src/Controls/samples/Controls.Sample/Pages/AppShell.xaml	Adds the new badge gallery and XAML examples using `BadgeText` / `BadgeColor`.

src/Controls/src/Core/Compatibility/Handlers/Shell/Android/ShellItemRenderer.cs

src/Controls/src/Core/Shell/BaseShellItem.cs

src/Controls/samples/Controls.Sample/Pages/Core/ShellGalleries/ShellBadgeGallery.cs

src/Controls/src/Core/PublicAPI/net-tizen/PublicAPI.Unshipped.txt

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

… alignment - Fix Android UpdateAllBadges to skip More tab when overflow exists - Fix ShellBadgeGallery nullable annotations (Color?, ShellSection?, IList?) - Align net-tizen PublicAPI entries with other TFMs (use ~ prefix) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add missing 'using Microsoft.Maui' for ClearButtonVisibility/Thickness - Fix event handler sender parameter to 'object?' for nullable compat Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

AlleSchonWeg · 2026-03-26T08:43:22Z

@jfversluis ,
thanks for this addition. Is it possible to also add this on a Microsoft.Maui.Controls.ToolbarItem? I know that is supported on iOS 26 (UIBarButtonItemBadge) and Android (BadgeDrawable).

jfversluis · 2026-03-26T10:33:45Z

/azp run maui-pr-uitests

azure-pipelines · 2026-03-26T10:33:58Z

Azure Pipelines successfully started running 1 pipeline(s).

Extends badge support from Shell bottom tabs (PR #34659) to ToolbarItems. Uses native platform APIs: Android BadgeUtils/BadgeDrawable, iOS 26+ UIBarButtonItem.badge, and Windows InfoBadge overlay. Includes 17 unit tests, UI test page, and sample gallery page. Fixes #8305 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jfversluis · 2026-03-26T13:17:07Z

/azp run maui-pr

jfversluis · 2026-03-26T13:17:09Z

/azp run maui-pr-uitests

azure-pipelines · 2026-03-26T13:17:20Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2026-03-26T13:17:24Z

Azure Pipelines successfully started running 1 pipeline(s).

…or customization - Add BadgeTextColor BindableProperty to BaseShellItem - Android: BadgeDrawable.BadgeTextColor - iOS/MacCatalyst: UITabBarItem.SetBadgeTextAttributes - Windows: InfoBadge.Foreground via NavigationViewItemViewModel.BadgeForeground - Update all platform handlers to track BadgeTextColor property changes - Add BadgeForeground property to NavigationViewItemViewModel (Windows) - Bind Foreground in TabbedPageStyle.xaml InfoBadge template - Add 6 unit tests for BadgeTextColor (25 total) - Update all 7 PublicAPI.Unshipped.txt files - Add Badge Text Color section to ShellBadgeGallery sample page Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jfversluis · 2026-03-26T19:25:23Z

/azp run maui-pr-uitests

Change BadgeText semantics: null = no badge, empty string = dot indicator, non-empty string = text/count badge. Previously both null and empty string hid the badge. Platform implementations: - Android: ClearNumber() on BadgeDrawable for dot mode - iOS: Set BadgeValue to empty string (native dot support) - Windows: HasBadge checks 'is not null' instead of IsNullOrEmpty Added 3 unit tests for dot badge behavior. Updated sample page dot badge button to use empty string. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jfversluis · 2026-03-27T09:58:52Z

/azp run maui-pr

jfversluis · 2026-03-27T09:59:02Z

/azp run maui-pr-uitests

azure-pipelines · 2026-03-27T09:59:07Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2026-03-27T09:59:13Z

Azure Pipelines successfully started running 1 pipeline(s).

Remove duplicate entries in net-android that caused RS0025 build errors. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jfversluis · 2026-03-27T13:14:26Z

/azp run maui-pr

jfversluis · 2026-03-27T13:14:28Z

/azp run maui-pr-uitests

azure-pipelines · 2026-03-27T13:14:36Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2026-03-27T13:14:38Z

Azure Pipelines successfully started running 1 pipeline(s).

Generated from CI build 1354596 (WinUI UITests Controls Shell). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jfversluis · 2026-03-27T13:18:39Z

/azp run maui-pr

jfversluis · 2026-03-27T13:18:40Z

/azp run maui-pr-uitests

azure-pipelines · 2026-03-27T13:18:50Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2026-03-27T13:18:51Z

Azure Pipelines successfully started running 1 pipeline(s).

- Add 4 iOS (ios-26) reference screenshots for Shell badge tests - Add 4 Android reference screenshots for Shell badge tests - Generated from CI build 1354898 snapshot artifacts Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jfversluis · 2026-03-27T15:00:54Z

/azp run maui-pr-uitests

jfversluis · 2026-03-27T15:00:56Z

/azp run maui-pr

azure-pipelines · 2026-03-27T15:01:05Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2026-03-27T15:01:07Z

Azure Pipelines successfully started running 1 pipeline(s).

Copilot AI review requested due to automatic review settings March 25, 2026 22:40

Copilot started reviewing on behalf of jfversluis March 25, 2026 22:41 View session

jfversluis and others added 2 commits March 25, 2026 23:44

jfversluis force-pushed the feature/shell-badge-support branch from d534554 to 55ad580 Compare March 25, 2026 22:44

Copilot AI reviewed Mar 25, 2026

View reviewed changes

Show badge on Home tab too for multiple badge scenarios

18f1a88

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jfversluis force-pushed the feature/shell-badge-support branch from 397f424 to 18f1a88 Compare March 25, 2026 22:55

github-actions bot mentioned this pull request Mar 26, 2026

[repo-status] Daily Repo Status - March 26, 2026 #34665

Closed

Fix ShellBadgeGallery build: add missing using and nullable annotations

a72ba60

- Add missing 'using Microsoft.Maui' for ClearButtonVisibility/Thickness - Fix event handler sender parameter to 'object?' for nullable compat Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

This was referenced Mar 26, 2026

CI UItests failure System.TimeoutException : Timed out waiting for element... #33220

Open

System.TimeoutException #33245

Open

jfversluis mentioned this pull request Mar 26, 2026

Add BadgeText, BadgeColor, and BadgeTextColor support to ToolbarItem #34669

Open

jfversluis changed the title ~~Add Shell badge notification support (BadgeText, BadgeColor)~~ Add Shell badge support (BadgeText, BadgeColor, BadgeTextColor) Mar 26, 2026

Fix duplicate PublicAPI.Unshipped.txt entries

aa1e274

Remove duplicate entries in net-android that caused RS0025 build errors. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add Windows reference screenshots for Shell badge UI tests

9baf9a5

Generated from CI build 1354596 (WinUI UITests Controls Shell). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Conversation

jfversluis commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

New API

XAML Usage

Platform Implementation

Dot Badge Support

What's Included

What's NOT Included (follow-up work)

Screenshots

Testing

Uh oh!

github-actions bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AlleSchonWeg commented Mar 26, 2026

Uh oh!

jfversluis commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

azure-pipelines bot commented Mar 26, 2026

Uh oh!

jfversluis commented Mar 26, 2026

Uh oh!

jfversluis commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

azure-pipelines bot commented Mar 26, 2026

Uh oh!

azure-pipelines bot commented Mar 26, 2026

Uh oh!

jfversluis commented Mar 26, 2026

Uh oh!

jfversluis commented Mar 27, 2026

Uh oh!

jfversluis commented Mar 27, 2026

Uh oh!

azure-pipelines bot commented Mar 27, 2026

Uh oh!

azure-pipelines bot commented Mar 27, 2026

Uh oh!

jfversluis commented Mar 27, 2026

Uh oh!

jfversluis commented Mar 27, 2026

Uh oh!

azure-pipelines bot commented Mar 27, 2026

Uh oh!

azure-pipelines bot commented Mar 27, 2026

Uh oh!

jfversluis commented Mar 27, 2026

Uh oh!

jfversluis commented Mar 27, 2026

Uh oh!

azure-pipelines bot commented Mar 27, 2026

Uh oh!

azure-pipelines bot commented Mar 27, 2026

Uh oh!

jfversluis commented Mar 27, 2026

Uh oh!

jfversluis commented Mar 27, 2026

Uh oh!

azure-pipelines bot commented Mar 27, 2026

Uh oh!

azure-pipelines bot commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

jfversluis commented Mar 25, 2026 •

edited

Loading

github-actions bot commented Mar 25, 2026 •

edited

Loading

jfversluis commented Mar 26, 2026 •

edited

Loading

jfversluis commented Mar 26, 2026 •

edited

Loading