Badge

The Badge and NumericBadge controls can be used to provide contextual information for other elements or used on their own.

Badge and NumericBadge controls displayed as adorners to an element

Content

The Content of Badge can be set to any value supported by ContentPresenter.

The following example demonstrates creating a Badge with the text "NEW!" as the content:

xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
...
<shared:Badge>NEW!</shared:Badge>

Alternatively, the ContentTemplate can also be used to define the content. The following example demonstrates defining one of the reusable glyph theme assets as the ContentTemplate.

xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
xmlns:themes="http://schemas.actiprosoftware.com/winfx/xaml/themes"
...
<shared:Badge Padding="0" ContentTemplate="{DynamicResource {x:Static themes:SharedResourceKeys.SmallMinusGlyphTemplateKey}}" />

Showing and Hiding

The visibility of a Badge is primarily managed by the IsActive property instead of the Visibility property. This is necessary to properly support animations when hiding the badge. The IsActive property defaults to true.

Animation

When shown (IsActive = true), the badge will animate into position using a "pop" animation. A similar but opposite animation is used when hiding (IsActive = false).

Animations are automatically disabled, as appropriate, based on system settings. To manually turn off animations, set the IsAnimationEnabled property to false.

NumericBadge

The NumericBadge control derives from the Badge and is purpose-built to automatically generate content based on the current value of the Count property.

The following example demonstrates how to define a NumericBadge:

xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
...
<shared:NumericBadge Count="5" />

Automatically Show and Hide

By default, the NumericBadge will be shown when the current Count property is greater than 0. Optionally, set the IsActiveWhenZero property to true and badge will also be shown when the count is 0. The badge will always be hidden when the count is negative.

Overflow

When the current value of the Count property exceeds the value of the OverflowCount property (which defaults to 99), the content will be displayed in an overflow format like "99+".

Use the OverflowStringFormat property to customize how overflowed counts are formatted. The default value is "{0}+", where {0} is the placeholder for the current value of OverflowCount.

Overflow behavior can be disabled by setting OverflowCount to 0.

The following example demonstrates how to define a NumericBadge that overlows at 9 and uses a custom string format of "{0}*":

xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
...
<shared:NumericBadge Count="5" OverflowCount="9" OverflowStringFormat="{}{0}*" />

Using as an adornment

A common scenario for a badge is to be used as an adornment to another element. Examples include showing availability status on a user's avatar or a count of unread messages.

Adornments are managed using attached properties of the BadgeService class.

Defining

To define a badge as an adornment to an element, assign a Badge or NumericBadge to the BadgeService.Badge attached property.

The following example demonstrates adding a NumericBadge adornment to a button to indicate a count of unread notifications:

xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
...

<Button Content="Notifications">

	<!-- Set any Badge or NumericBadge as an adornment -->
	<shared:BadgeService.Badge>
		<shared:NumericBadge Count="5" />
	</shared:BadgeService.Badge>

</Button>

Alignment

By default, a badge adornment is displayed with the center of the adornment over the center of the top-right edge of the adorned element. The following attached properties on BadgeService can be used to configure the alignment:

The following example demonstrates aligning the adornment inside the bottom right corner with an additional horizontal and vertical offset to allow space between the adornment and the adorned element's edge:

xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
...

<Button ...
	shared:BadgeService.HorizontalAlignment="InsideOfTargetRightEdge"
	shared:BadgeService.VerticalAlignment="InsideOfTargetBottomEdge"
	shared:BadgeService.HorizontalOffset="-4"
	shared:BadgeService.VerticalOffset="-4"
	>

	<shared:BadgeService.Badge>
		<shared:Badge Content="Custom Alignment" />
	</shared:BadgeService.Badge>

</Button>

Badge Kind

A badge can either display its content or, alternatively, always display as a "dot" without content.

The Dot kind is useful for smaller elements that do not have enough room to adequately display badge content. It can also be useful if the mere existence of the badge is all that is needed, and content is not necessary.

The following values can be assigned to the Kind property:

In the following example, both badges will appear as a "dot":

xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
...

<!-- No content, so 'Default' kind will effectively display as a 'Dot' -->
<shared:Badge />

<!-- Explicit 'Dot' kind even though content is available -->
<shared:Badge Kind="Dot" Content="Ignored" />

Padding

By default, the Padding is uniformly set to 0 unless the badge is displaying String-based content.

For String-based content, a default padding will be assigned that improves the default appearance of textual content.

Accessibility

The Badge and NumericBadge controls are non-interactive decorations and, as such, intentionally do not appear in the default user interface automation (UIA) views used by most screen readers or automation tools.

For any information displayed in a badge, developers should consider adding equivalent information to the associated element using one or more of the attached properties on the AutomationProperties class; e.g., AutomationProperties.ItemStatus.