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

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

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.

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.

/azp run maui-pr-uitests

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)

/azp run maui-pr

/azp run maui-pr-uitests

also this issue #23802 will be solved by this pr

/azp run maui-pr

/azp run maui-pr-uitests

/azp run maui-pr-uitests

/azp run maui-pr

/azp run maui-pr-uitests

Code Review Summary

Adds BadgeText, BadgeColor, and BadgeTextColor bindable properties to ToolbarItem with platform implementations for Android (Material BadgeDrawable), iOS/macCatalyst (iOS 26+ native UIBarButtonItem.badge), and Windows (InfoBadge overlay). Targets net11.0 branch appropriately as a delighter feature with new API surface. The API naming and semantics (null=hidden, ""=dot, text=badge) are consistent with the companion Shell badge PR (#34659). PublicAPI files are updated for all 7 TFMs. Unit test coverage (27 tests) and UI tests (4 tests with screenshots on 3 platforms) are solid.

Findings

🔴 Critical

Android: WeakReference not unwrapped in race condition guard (ToolbarExtensions.cs, UpdateToolbarItemBadge)

Inside the toolbar.Post() callback, the race condition guard does:

if (_menuItemToolbarItemMap.TryGetValue(menuItemId, out var currentToolbarItem) &&
    !ReferenceEquals(currentToolbarItem, toolbarItem))
    return;

_menuItemToolbarItemMap is a ConcurrentDictionary<int, WeakReference<ToolbarItem>>, so currentToolbarItem here is a WeakReference<ToolbarItem>, not a ToolbarItem. ReferenceEquals(WeakReference<T>, T) will always return false, making !ReferenceEquals(...) always true, causing the guard to always bail out — meaning badges would never render through this path.

The existing correct pattern in the same file (UpdateMenuItemIcon, ~line 466) properly unwraps:

if (!_menuItemToolbarItemMap.TryGetValue(menuItem.ItemId, out var weakRef)
    || !weakRef.TryGetTarget(out var currentToolbarItem)
    || !ReferenceEquals(currentToolbarItem, toolBarItem))
    return;

Suggested fix: Use TryGetTarget to unwrap the WeakReference before comparing.

🟡 Warnings

1. Android: _badgeDrawables is static but DisposeMenuItems clears ALL entries globally (ToolbarExtensions.cs)

   DisposeMenuItems iterates all _badgeDrawables.Keys and cleans up every badge. Since _badgeDrawables is static, this would remove badges from other active toolbars if multiple exist simultaneously (e.g., during page navigation transitions). Consider scoping cleanup to only the menu item IDs belonging to the current toolbar being disposed, similar to how _menuItemToolbarItemMap cleanup is scoped to specific item IDs.

2. Windows: Grid+InfoBadge wrapper created for ALL icon-based toolbar items (Toolbar.Windows.cs)

   The code unconditionally wraps every icon-based toolbar item in a WGrid + hidden InfoBadge, even when BadgeText is null. This changes the visual tree for all toolbar items and adds overhead. Consider only creating the Grid wrapper when item.BadgeText is not null, and handling the first-badge case in OnToolbarItemPropertyChanged (similar to how text-only items are handled conditionally).

3. Windows: Non-numeric badge text silently falls back to dot indicator

   On Windows, UpdateInfoBadge maps non-numeric text (e.g., "New") to badge.Value = -1 (dot indicator). This means Windows has less badge fidelity than Android/iOS where text badges are fully supported. The PR description documents this, but consider adding a runtime note via Debug.WriteLine when text is silently downgraded.

🔵 Info

4. API consistency with Shell badges (PR Add Shell badge support (BadgeText, BadgeColor, BadgeTextColor) #34659): ✅ Property names, types, default values, and null/empty-string semantics are fully consistent.

5. iOS snapshots in ios-26/ folder: The test infrastructure supports ios-26 environment-specific snapshots, which is correct since badges require iOS 26+. On pre-iOS 26 CI runners, these VerifyScreenshot tests may fail if no fallback ios/ reference images exist. Verify that CI handles missing reference images gracefully (skip vs fail).

6. Tizen: PublicAPI entries added but no platform implementation — properties will be no-ops. This is fine but worth documenting in platform support notes.

7. Unrelated Maps PublicAPI change: The src/Core/maps/src/PublicAPI/net/PublicAPI.Unshipped.txt change removes a duplicate HideInfoWindow entry (without nullable annotation). This is a correct cleanup but unrelated to badge support — consider separating into its own commit for cleaner history.

8. XML documentation: Excellent — thorough per-platform docs with remarks, lists, and cross-references on all three properties.

Overall Assessment

Well-structured feature with consistent API design, good test coverage, and thoughtful platform-specific implementations. The Android WeakReference comparison bug (🔴) needs to be fixed before merge — it follows the wrong pattern compared to the existing UpdateMenuItemIcon code in the same file and would prevent badges from rendering on Android via the Post callback path. The static _badgeDrawables cleanup scope (🟡) is also worth addressing to prevent edge cases with concurrent toolbars.

Review performed by Copilot CLI

Code Review Summary (Updated)

ToolbarItem badge support — Adds BadgeText, BadgeColor, BadgeTextColor to ToolbarItem across Android, iOS 26+, and Windows. API consistent with Shell badges (PR #34659).

Findings

Overall Assessment

⚠️ The WeakReference comparison bug is critical and must be fixed before merge. The existing correct pattern is in the same file — use TryGetTarget instead of ReferenceEquals.

Review performed by Copilot CLI

Code Review — PR #34669

Independent Assessment

What this changes: Adds BadgeText, BadgeColor, and BadgeTextColor bindable properties to ToolbarItem with platform implementations for Android (Material BadgeDrawable), iOS/MacCatalyst 26+ (native UIBarButtonItem.badge), and Windows (InfoBadge overlay). Includes 27 unit tests, 4 UI tests with screenshots, a gallery sample page, and all 7 PublicAPI.Unshipped.txt files updated.

Target branch: net11.0 — correct for a new API feature.

Reconciliation with PR Narrative

Agreement: ✅ Code matches the description. All claimed API semantics (null = hidden, empty = dot, non-empty = text/count) are correctly implemented across all three platforms. The .NET 11.0-preview4 milestone is appropriate.

Findings

✅ Good — Clean API design

• Three bindable properties with clear nullable semantics and comprehensive XML documentation
• null = no badge, "" = dot indicator, non-empty = text/count — intuitive and consistent
• Properties are on ToolbarItem (shared cross-platform type), with platform rendering handled in platform-specific code
• All 7 PublicAPI.Unshipped.txt files updated with correct nullable annotations (~ prefix)

✅ Good — Android: Robust race condition handling

• ConcurrentDictionary<int, WeakReference<ToolbarItem>> maps menu item IDs to toolbar items — prevents stale async icon callbacks from updating wrong items
• ConcurrentDictionary<int, BadgeDrawable> tracks badge drawables for cleanup
• toolbar.Post() defers badge attachment until layout is complete
• Triple guard in the posted callback: (1) IsAttachedToWindow check, (2) BadgeText staleness check, (3) _menuItemToolbarItemMap identity check
• Try/catch fallback for BadgeUtils.AttachBadgeDrawable → UpdateBadgeCoordinates + overlay
• Cleanup in DisposeMenuItems and when menu items are removed

✅ Good — iOS: Correct version check and implementation

if (!OperatingSystem.IsIOSVersionAtLeast(26) && !OperatingSystem.IsMacCatalystVersionAtLeast(26))
    return;

Matches the established codebase pattern for iOS 26+ APIs. Correct mapping: Create(0) for dot, Create(count) for numeric, Create(string) for text. #pragma warning disable CA1416 is appropriate.

✅ Good — Windows: Proper InfoBadge overlay

Grid wrapping pattern for both icon-based and text-only toolbar items. Dynamic badge changes handled via OnToolbarItemPropertyChanged which either updates existing InfoBadge or wraps content for newly-badged items.

✅ Good — Comprehensive test coverage

• 27 unit tests covering all property defaults, get/set, clearing, PropertyChanged events, XAML data binding, and edge cases (empty string, whitespace, negative numbers, emoji)
• 4 UI tests with VerifyScreenshot(retryTimeout: TimeSpan.FromSeconds(2)) — correctly accounts for async Android badge rendering
• Screenshots provided for Android, iOS 26, and Windows
• All prior review threads (14) resolved

💡 Observation — Static dictionaries for Android badge tracking

_menuItemToolbarItemMap and _badgeDrawables are static readonly ConcurrentDictionary fields. This is acceptable because:

• Menu item IDs are globally unique (AView.GenerateViewId())
• Entries are cleaned up in DisposeMenuItems and when items are removed
• WeakReference<ToolbarItem> prevents strong-reference leaks

However, if DisposeMenuItems is ever not called (e.g., abnormal cleanup path), entries could accumulate. The WeakReference for ToolbarItem helps, but BadgeDrawable objects are strong references. This is a minor theoretical concern — the cleanup paths appear comprehensive.

💡 Observation — ToolbarItem.cs uses #nullable disable

The file-level #nullable disable means BadgeText, BadgeColor, and BadgeTextColor are technically non-nullable at the C# level, but the BindableProperty defaults are default(string) and default(Color) (both null). The PublicAPI entries use ~ prefix (nullable-oblivious). This is consistent with the existing pattern in the file (OrderProperty, PriorityProperty also use default values under #nullable disable). No action needed — just noting for awareness.

ℹ️ Note — Tizen has no implementation

Badge properties are registered in PublicAPI for Tizen but there's no Tizen-specific rendering code. Setting BadgeText on Tizen will be a no-op. This is acceptable — the properties exist cross-platform and platforms implement rendering as they support it.

ℹ️ Note — CI Status

No CI failures detected. Clean build.

Devil's Advocate

• "Should BadgeText be an int? instead of string??" — No. The string type correctly supports numeric counts ("3"), text badges ("New"), dot indicators (""), and hidden (null). An int would require a separate "badge mode" property.
• "Could the static ConcurrentDictionaries cause memory pressure?" — Unlikely. Entries are cleaned up on disposal and menu item removal. Menu item IDs are ints (4 bytes per entry). The dictionaries would only grow if toolbars are created/destroyed without proper cleanup.
• "Why iOS 26+ only?" — UIBarButtonItem.badge is a new API in iOS 26. Earlier iOS versions have no native badge support for bar button items. The PR correctly no-ops on earlier versions.
• "Will the Windows Grid wrapping break custom toolbar item templates?" — The Grid wrapping only applies when BadgeText is non-null. Standard toolbar items without badges are unaffected.

Verdict: LGTM

Confidence: high
Summary: Well-designed new feature with clean API, robust platform implementations (especially the Android race condition handling), comprehensive test coverage (27 unit + 4 UI tests), and all prior review feedback resolved. The API semantics are intuitive, the implementations follow platform conventions, and the PublicAPI entries are correct. Ready for merge.

Review performed by Copilot CLI using the code-review skill

🧪 PR Test Evaluation

Overall Verdict: ⚠️ Tests need improvement

The PR adds solid unit test coverage for badge property logic and appropriate screenshot-based UI tests for visual rendering. A few conventions issues and missing robustness improvements in the Shell badge UI tests should be addressed before merge.

👍 / 👎 — Was this evaluation helpful? React to let us know!

network:
  allowed:
    - defaults
    - "dc.services.visualstudio.com"

🧪 Test evaluation by Evaluate PR Tests

🚨 API change(s) detected @davidortinau FYI