Add BadgeText, BadgeColor, and BadgeTextColor support to ToolbarItem by jfversluis · Pull Request #34669 · dotnet/maui

jfversluis · 2026-03-26T13:12: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 BadgeText, BadgeColor, and BadgeTextColor properties to ToolbarItem, enabling badge notifications on toolbar items across all platforms.

Fixes #8305 (partial - ToolbarItem badges; Shell tab badges handled in #34659)

API

// Set a numeric badge
toolbarItem.BadgeText = "5";

// Set a text badge  
toolbarItem.BadgeText = "New";

// Dot indicator (small badge with no text)
toolbarItem.BadgeText = "";

// Custom badge colors
toolbarItem.BadgeColor = Colors.Blue;
toolbarItem.BadgeTextColor = Colors.White;

// Clear badge
toolbarItem.BadgeText = null;

Badge Text Semantics

Value	Behavior
`null`	No badge (hidden)
`""` (empty string)	Dot indicator
`"3"`	Numeric count badge
`"New"`	Text badge

Platform Support

Platform	Implementation	Notes
Android	`BadgeDrawable` via Material Components	Full text + color support. `ClearNumber()` for dot mode. Uses `BadgeUtils.attachBadgeDrawable()` with race condition guard.
iOS 26+	Native `UIBarButtonItem.badge` API	Numeric and text badges. `Create(0)` for dot. Requires iOS 26+, no-op on earlier versions.
macOS (Catalyst 26+)	Same as iOS	Shares iOS implementation via Catalyst.
Windows	`InfoBadge` overlay on `AppBarButton`	Numeric values show count; non-numeric text and empty string show dot indicator.

Properties

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

Changes

ToolbarItem.cs — Added BadgeText, BadgeColor, BadgeTextColor bindable properties with XML docs
ToolbarExtensions.cs (Android) — Badge rendering via BadgeDrawable with ConcurrentDictionary tracking, stale-update guard, and cleanup in DisposeMenuItems
ToolbarItemExtensions.cs (iOS) — iOS 26+ native badge API with platform version check
Toolbar.Windows.cs — InfoBadge overlay on AppBarButton content grid (both icon and text-only items)
27 unit tests in ToolbarItemBadgeTests.cs
4 UI tests (HostApp page + NUnit test with screenshots)
Sample gallery page ToolbarBadgePage.cs
All 7 PublicAPI.Unshipped.txt files updated

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>

- Replace deprecated Frame with Border control - Add System and Microsoft.Maui usings - Fix nullable Color? parameter in SetBadgeColor Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-03-26T13:12:41Z

🚀 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 -- 34669

Or

Run remotely in PowerShell:

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

Copilot

Pull request overview

Adds cross-platform badge support to ToolbarItem via new BadgeText/BadgeColor bindable properties, with platform renderers and accompanying tests/samples.

Changes:

Introduces ToolbarItem.BadgeText and ToolbarItem.BadgeColor plus PublicAPI updates.
Implements badge rendering on Android (Material BadgeDrawable), iOS/MacCatalyst (native UIBarButtonItem badge), and Windows (InfoBadge overlay).
Adds unit tests, UI tests (HostApp + Appium), and a sample gallery page demonstrating toolbar badges.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
src/Controls/src/Core/Toolbar/ToolbarItem.cs	Adds `BadgeText`/`BadgeColor` bindable properties and XML docs.
src/Controls/src/Core/Platform/Android/Extensions/ToolbarExtensions.cs	Renders badges with `BadgeDrawable`, includes lifecycle tracking and async attachment logic.
src/Controls/src/Core/Compatibility/iOS/Extensions/ToolbarItemExtensions.cs	Updates iOS primary toolbar item wrapper to apply native badge when supported.
src/Controls/src/Core/Toolbar/Toolbar.Windows.cs	Adds `InfoBadge` overlay and updates it on `ToolbarItem` property changes.
src/Controls/src/Core/PublicAPI/*/PublicAPI.Unshipped.txt	Adds unshipped PublicAPI entries for the new `ToolbarItem` badge members across TFMs.
src/Controls/tests/Core.UnitTests/ToolbarItemBadgeTests.cs	Unit tests for default values, binding, and property-changed behavior.
src/Controls/tests/TestCases.HostApp/Issues/Issue8305_Toolbar.cs	HostApp page used by UITests to exercise badge scenarios.
src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue8305_Toolbar.cs	Appium UI tests + screenshots for toolbar badge scenarios.
src/Controls/samples/Controls.Sample/ViewModels/CoreViewModel.cs	Registers the new sample page in the gallery navigation.
src/Controls/samples/Controls.Sample/Pages/Core/ToolbarBadgePage.cs	Sample page demonstrating numeric/text badges and color changes.
src/Core/maps/src/PublicAPI/net/PublicAPI.Unshipped.txt	Removes duplicate/unannotated entries for `IMap.ShowInfoWindow/HideInfoWindow`.

src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue8305_Toolbar.cs

src/Controls/src/Core/Toolbar/Toolbar.Windows.cs

src/Controls/src/Core/Toolbar/ToolbarItem.cs

src/Controls/src/Core/PublicAPI/netstandard/PublicAPI.Unshipped.txt

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

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

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

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

src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue8305_Toolbar.cs

The test file was missing NUnit.Framework, UITest.Appium, and UITest.Core usings, and used incorrect namespace causing build failures in Controls.TestCases.Mac.Tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

AlleSchonWeg · 2026-03-26T15:12:14Z

Hi @jfversluis
i have implemented a toolbaritem badge in my app. You have added BadgeColor (BackgroundColor) and BadgeText. Good start.
Also important is:
TextColor --> UIBarButtonItemBadge.ForegroundColor and BadgeDrawable.BadgeTextColor
IsVisible --> UIBarButtonItem.Badge = null and BadgeDrawable.SetVisible()

Nice to have:
BadgeTextFont

…text-only items, Android cleanup - Add BadgeTextColor property to ToolbarItem for foreground text color customization - Android: BadgeDrawable.BadgeTextColor - iOS/MacCatalyst 26+: UIBarButtonItemBadge.ForegroundColor - Windows: InfoBadge.Foreground brush - Add retryTimeout to all VerifyScreenshot() calls for async Android badge rendering - Fix Windows text-only toolbar items: wrap in Grid+InfoBadge overlay - Add ReferenceEquals guard in Android toolbar.Post() callback for recycled menu items - Clean up all badge drawables in DisposeMenuItems - Add 7 unit tests for BadgeTextColor (24 total) - Update all 7 PublicAPI.Unshipped.txt files - Add Badge Text Color section to sample gallery page Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jfversluis · 2026-03-26T15:35:45Z

Thanks for the feedback @AlleSchonWeg! Great to hear you've implemented toolbar badges in your app.

BadgeTextColor — Implemented in 374ae80! New BadgeTextColor property maps to:

Android: BadgeDrawable.BadgeTextColor
iOS/MacCatalyst 26+: UIBarButtonItemBadge.ForegroundColor
Windows: InfoBadge.Foreground

IsVisible — Setting BadgeText = null already clears the badge completely (which effectively hides it). Adding a separate IsVisible property would add complexity without significant benefit since the same result is achieved by toggling BadgeText. If there's a specific use case where you need to preserve the text while hiding the badge, we can revisit this.

BadgeTextFont — This is tricky as platform support varies significantly. Android's BadgeDrawable doesn't expose font customization, and iOS's UIBarButtonItemBadge is similarly limited. We'll leave this out for now but could add it in a future iteration if platform APIs evolve.

AlleSchonWeg · 2026-03-26T17:51:34Z

Thanks for implementing my suggestion @jfversluis

IsVisible — Setting BadgeText = null already clears the badge completely (which effectively hides it). Adding a separate IsVisible property would add complexity without significant benefit since the same result is achieved by toggling BadgeText. If there's a specific use case where you need to preserve the text while hiding the badge, we can revisit this.

I find setting BadgeText = null not intuitive. and the developer must know that it works this way. Almost every UI-Control has a IsVisible property. As a dev i would check this property first.
Setting an empty/null text i could also create a indicator on a toolbaritem. Many apps have a small red point on a toolbar item which indicates "that there is something". Sometimes a new setting or something thats needs attention. (https://m2.material.io/develop/android/supporting/badge)

As i implemented my badge i observed a crazy behaviour on android. I added the badge on a toolbar item on one page and on another page(s) the badge also appeared. But only the badge. The icon, color etc. was correct. I don't know if i had done something wrong. Perhaps some internal caching or whatever. My setup was a TabbedPage with 4 tabs. Every tab had a NavigationPage and on the first Root ContentPage i had the item with badge plus another item without badge. The other Root ContentPages had also toolbar items but without badges. Perhaps this info can help with your implementation.

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

/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: UIBarButtonItemBadge.Create(0) for dot indicator - Windows: Value = -1 for empty string (dot indicator) Added 3 unit tests for dot badge behavior. Updated XML docs to document null vs empty string semantics. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jfversluis · 2026-03-26T19:38:46Z

Implemented dot badge support! You can now set BadgeText = "" (empty string) to show a small dot indicator badge without any text. The semantics are:

null → no badge (hidden)
"" (empty string) → dot indicator
"3" → count badge
"New" → text badge

Platform-specific behavior:

Android: Uses BadgeDrawable.ClearNumber() which displays the native dot mode
iOS/MacCatalyst: Uses UIBarButtonItemBadge.Create(0) for a minimal dot
Windows: Uses InfoBadge.Value = -1 which renders as a dot

This applies to both PRs (#34659 Shell tabs and #34669 ToolbarItems).

Commit: 1d1549c (toolbar) and 39c8d64 (shell)

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

/azp run maui-pr

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

/azp run maui-pr-uitests

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

Azure Pipelines successfully started running 1 pipeline(s).

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

Azure Pipelines successfully started running 1 pipeline(s).

bronteq · 2026-03-27T12:01:03Z

also this issue #23802 will be solved by this pr

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

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

/azp run maui-pr

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

/azp run maui-pr-uitests

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

Azure Pipelines successfully started running 1 pipeline(s).

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

Azure Pipelines successfully started running 1 pipeline(s).

- Remove WaitForElement for ToolbarItem AutomationId (not accessible via Appium on WinUI) — wait for page StatusLabel instead - Add Windows reference screenshots for ToolbarItemBadgesClear and ToolbarItemBadgeColorChanges tests Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jfversluis · 2026-03-27T14:50:34Z

/azp run maui-pr-uitests

azure-pipelines · 2026-03-27T14:50:44Z

Azure Pipelines successfully started running 1 pipeline(s).

jfversluis · 2026-03-27T14:50:45Z

/azp run maui-pr

azure-pipelines · 2026-03-27T14:50:56Z

Azure Pipelines successfully started running 1 pipeline(s).

- Add 3 iOS (ios-26) reference screenshots: ToolbarItemBadgesDisplay, ToolbarItemBadgesClear, ToolbarItemBadgeColorChanges - Add 3 Android reference screenshots for the same tests - Generated from CI build 1355044 snapshot artifacts Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

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

jfversluis · 2026-03-27T16:29:59Z

/azp run maui-pr-uitests

azure-pipelines · 2026-03-27T16:30:10Z

Azure Pipelines successfully started running 1 pipeline(s).

jfversluis and others added 2 commits March 26, 2026 11:52

Fix ToolbarBadgePage compilation: Frame->Border, add missing usings

af3075e

- Replace deprecated Frame with Border control - Add System and Microsoft.Maui usings - Fix nullable Color? parameter in SetBadgeColor Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings March 26, 2026 13:12

Copilot started reviewing on behalf of jfversluis March 26, 2026 13:13 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

jfversluis changed the title ~~Add BadgeText and BadgeColor support to ToolbarItem~~ Add BadgeText, BadgeColor, and BadgeTextColor support to ToolbarItem Mar 26, 2026

Fix duplicate PublicAPI.Unshipped.txt entries

2c8ddc1

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

jfversluis and others added 2 commits March 27, 2026 17:18

Add Windows ToolbarItemBadgesDisplay reference screenshot

f95a346

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

Conversation

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

Uh oh!

Description

API

Badge Text Semantics

Platform Support

Properties

Changes

Uh oh!

github-actions bot commented Mar 26, 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AlleSchonWeg commented Mar 26, 2026

Uh oh!

jfversluis commented Mar 26, 2026

Uh oh!

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

Uh oh!

Uh oh!

jfversluis 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!

bronteq 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!

azure-pipelines bot commented Mar 27, 2026

Uh oh!

jfversluis commented Mar 27, 2026

Uh oh!

azure-pipelines bot commented Mar 27, 2026

Uh oh!

jfversluis commented Mar 27, 2026

Uh oh!

azure-pipelines bot commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jfversluis commented Mar 26, 2026 •

edited

Loading

github-actions bot commented Mar 26, 2026 •

edited

Loading

AlleSchonWeg commented Mar 26, 2026 •

edited

Loading