Support dot badge via empty string BadgeText

jfversluis · Copilot · jfversluis · commit 39c8d64f0dc9 · 2026-03-26T20:37:46.000+01:00
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 &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/src/Controls/samples/Controls.Sample/Pages/Core/ShellGalleries/ShellBadgeGallery.cs b/src/Controls/samples/Controls.Sample/Pages/Core/ShellGalleries/ShellBadgeGallery.cs
@@ -55,6 +55,7 @@ public ShellBadgeGallery()
 						new Label { Text = "Apply Badge to Tab", FontAttributes = FontAttributes.Bold },
 						CreateApplyButton("Set Badge on Current Tab", OnSetBadgeCurrentTab),
 						CreateApplyButton("Set Badge on All Tabs", OnSetBadgeAllTabs),
+						CreateApplyButton("Set Dot Badge (empty string)", OnSetDotBadge),
 						CreateApplyButton("Clear All Badges", OnClearAllBadges),
 
 						new BoxView { HeightRequest = 1, Color = Colors.LightGray },
@@ -179,8 +180,8 @@ void OnSetDotBadge(object? sender, EventArgs e)
 			var section = GetCurrentShellSection();
 			if (section is not null)
 			{
-				// A non-null but empty-looking badge on some platforms shows as a dot
-				section.BadgeText = " ";
+				// Empty string shows as a dot indicator on all platforms
+				section.BadgeText = "";
 				UpdateBadgeStatus();
 			}
 		}
diff --git a/src/Controls/src/Core/Compatibility/Handlers/Shell/Android/ShellItemRenderer.cs b/src/Controls/src/Core/Compatibility/Handlers/Shell/Android/ShellItemRenderer.cs
@@ -521,7 +521,7 @@ protected virtual void UpdateShellSectionBadge(ShellSection shellSection, int in
 			var badgeText = shellSection.BadgeText;
 			var menuItemId = index;
 
-			if (string.IsNullOrEmpty(badgeText))
+			if (badgeText is null)
 			{
 				_bottomView.RemoveBadge(menuItemId);
 			}
@@ -536,7 +536,10 @@ protected virtual void UpdateShellSectionBadge(ShellSection shellSection, int in
 				}
 
 				var badge = _bottomView.GetOrCreateBadge(menuItemId);
-				badge.Text = badgeText;
+				if (badgeText.Length > 0)
+					badge.Text = badgeText;
+				else
+					badge.ClearNumber(); // Empty string shows as dot indicator
 
 				if (badgeColor is not null)
 				{
diff --git a/src/Controls/src/Core/Compatibility/Handlers/Shell/iOS/ShellItemRenderer.cs b/src/Controls/src/Core/Compatibility/Handlers/Shell/iOS/ShellItemRenderer.cs
@@ -343,7 +343,7 @@ void SetTabItemsEnabledState()
 		static void UpdateTabBarItemBadge(UITabBarItem tabBarItem, ShellSection shellSection)
 		{
 			var badgeText = shellSection.BadgeText;
-			tabBarItem.BadgeValue = string.IsNullOrEmpty(badgeText) ? null : badgeText;
+			tabBarItem.BadgeValue = badgeText is null ? null : (badgeText.Length > 0 ? badgeText : "");
 
 			var badgeColor = shellSection.BadgeColor;
 			if (badgeColor is not null)
diff --git a/src/Controls/src/Core/Shell/BaseShellItem.cs b/src/Controls/src/Core/Shell/BaseShellItem.cs
@@ -166,7 +166,8 @@ public bool FlyoutItemIsVisible
 		/// </summary>
 		/// <remarks>
 		/// Setting this property to a non-null, non-empty value will display a badge on the tab item.
-		/// Set to <see langword="null"/> or empty string to hide the badge.
+		/// Set to an empty string to show a dot indicator (small badge with no text).
+		/// Set to <see langword="null"/> to hide the badge.
 		/// On Windows, only numeric values are displayed as numbers; non-numeric text (e.g., "New") shows as a dot indicator.
 		/// </remarks>
 		public string BadgeText
diff --git a/src/Controls/tests/Core.UnitTests/ShellBadgeTests.cs b/src/Controls/tests/Core.UnitTests/ShellBadgeTests.cs
@@ -251,5 +251,37 @@ public void BadgeTextColorSupportsDataBinding()
 			shellSection.BindingContext = new { TextColor = Colors.Cyan };
 			Assert.Equal(Colors.Cyan, shellSection.BadgeTextColor);
 		}
+
+		[Fact]
+		public void SetBadgeTextEmptyStringForDotBadge()
+		{
+			var shellSection = new ShellSection();
+			shellSection.BadgeText = "";
+			Assert.Equal("", shellSection.BadgeText);
+		}
+
+		[Fact]
+		public void EmptyStringBadgeIsDistinctFromNull()
+		{
+			var shellSection = new ShellSection();
+			shellSection.BadgeText = "";
+			Assert.NotNull(shellSection.BadgeText);
+			shellSection.BadgeText = null;
+			Assert.Null(shellSection.BadgeText);
+		}
+
+		[Fact]
+		public void EmptyStringBadgeFiresPropertyChanged()
+		{
+			var shellSection = new ShellSection();
+			bool fired = false;
+			shellSection.PropertyChanged += (s, e) =>
+			{
+				if (e.PropertyName == nameof(BaseShellItem.BadgeText))
+					fired = true;
+			};
+			shellSection.BadgeText = "";
+			Assert.True(fired);
+		}
 	}
 }
diff --git a/src/Core/src/Platform/Windows/NavigationViewItemViewModel.cs b/src/Core/src/Platform/Windows/NavigationViewItemViewModel.cs
@@ -274,7 +274,7 @@ public WBrush? BadgeForeground
 			set { this.SetProperty(ref _badgeForeground, value, OnPropertyChanged); }
 		}
 
-		public bool HasBadge => !string.IsNullOrEmpty(_badgeText);
+		public bool HasBadge => _badgeText is not null;
 
 		public int BadgeValue => int.TryParse(_badgeText, out var v) && v >= 0 ? v : -1;
 

Original file line number	Diff line number	Diff line change
`@@ -55,6 +55,7 @@ public ShellBadgeGallery()`
`55`	`55`	`new Label { Text = "Apply Badge to Tab", FontAttributes = FontAttributes.Bold },`
`56`	`56`	`CreateApplyButton("Set Badge on Current Tab", OnSetBadgeCurrentTab),`
`57`	`57`	`CreateApplyButton("Set Badge on All Tabs", OnSetBadgeAllTabs),`
	`58`	`+ CreateApplyButton("Set Dot Badge (empty string)", OnSetDotBadge),`
`58`	`59`	`CreateApplyButton("Clear All Badges", OnClearAllBadges),`
`59`	`60`
`60`	`61`	`new BoxView { HeightRequest = 1, Color = Colors.LightGray },`
`@@ -179,8 +180,8 @@ void OnSetDotBadge(object? sender, EventArgs e)`
`179`	`180`	`var section = GetCurrentShellSection();`
`180`	`181`	`if (section is not null)`
`181`	`182`	`{`
`182`		`- // A non-null but empty-looking badge on some platforms shows as a dot`
`183`		`- section.BadgeText = " ";`
	`183`	`+ // Empty string shows as a dot indicator on all platforms`
	`184`	`+ section.BadgeText = "";`
`184`	`185`	`UpdateBadgeStatus();`
`185`	`186`	`}`
`186`	`187`	`}`
Original file line number	Diff line number	Diff line change
`@@ -521,7 +521,7 @@ protected virtual void UpdateShellSectionBadge(ShellSection shellSection, int in`
`521`	`521`	`var badgeText = shellSection.BadgeText;`
`522`	`522`	`var menuItemId = index;`
`523`	`523`
`524`		`- if (string.IsNullOrEmpty(badgeText))`
	`524`	`+ if (badgeText is null)`
`525`	`525`	`{`
`526`	`526`	`_bottomView.RemoveBadge(menuItemId);`
`527`	`527`	`}`
`@@ -536,7 +536,10 @@ protected virtual void UpdateShellSectionBadge(ShellSection shellSection, int in`
`536`	`536`	`}`
`537`	`537`
`538`	`538`	`var badge = _bottomView.GetOrCreateBadge(menuItemId);`
`539`		`- badge.Text = badgeText;`
	`539`	`+ if (badgeText.Length > 0)`
	`540`	`+ badge.Text = badgeText;`
	`541`	`+ else`
	`542`	`+ badge.ClearNumber(); // Empty string shows as dot indicator`
`540`	`543`
`541`	`544`	`if (badgeColor is not null)`
`542`	`545`	`{`
Original file line number	Diff line number	Diff line change
`@@ -343,7 +343,7 @@ void SetTabItemsEnabledState()`
`343`	`343`	`static void UpdateTabBarItemBadge(UITabBarItem tabBarItem, ShellSection shellSection)`
`344`	`344`	`{`
`345`	`345`	`var badgeText = shellSection.BadgeText;`
`346`		`- tabBarItem.BadgeValue = string.IsNullOrEmpty(badgeText) ? null : badgeText;`
	`346`	`+ tabBarItem.BadgeValue = badgeText is null ? null : (badgeText.Length > 0 ? badgeText : "");`
`347`	`347`
`348`	`348`	`var badgeColor = shellSection.BadgeColor;`
`349`	`349`	`if (badgeColor is not null)`
Original file line number	Diff line number	Diff line change
`@@ -274,7 +274,7 @@ public WBrush? BadgeForeground`
`274`	`274`	`set { this.SetProperty(ref _badgeForeground, value, OnPropertyChanged); }`
`275`	`275`	`}`
`276`	`276`
`277`		`- public bool HasBadge => !string.IsNullOrEmpty(_badgeText);`
	`277`	`+ public bool HasBadge => _badgeText is not null;`
`278`	`278`
`279`	`279`	`public int BadgeValue => int.TryParse(_badgeText, out var v) && v >= 0 ? v : -1;`
`280`	`280`