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:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:Badge>NEW!</actipro: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:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:Badge Padding="0" ContentTemplate="{actipro:GlyphTemplate SmallCheck16}" />

Showing and Hiding

The visibility of a Badge is primarily managed by the IsActive property instead of the IsVisible 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 enabled. To 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:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro: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.

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:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...

<Button Content="Notifications">

	<!-- Set any Badge or NumericBadge as an adornment -->
	<actipro:BadgeService.Badge>
		<actipro:NumericBadge Count="5" />
	</actipro: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:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...

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

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

</Button>

Notes on Avalonia Adorner Issues

The Avalonia adorner system (last tested on v11.0.7) doesn't properly clip adornments based on the clip regions of ancestors of the adorned element. This is an issue we are working with the Avalonia team to solve. A symptom of this issue can sometimes be seen when a badge adornment is used on an adorned element, that adorned element is scrolled out of view within a ScrollViewer, and the badge adornment remains visible.

If this scenario is encountered, a workaround is to not use BadgeService, thereby avoiding use of the Avalonia adorner system. Place the adorned element and the badge element in a Panel instead and apply the HorizontalAlignment, VerticalAlignment, and RenderTransform properties on the badge to position it.

<Panel>
	<actipro:Avatar Width="64" CornerRadius="10" Description="User Name" />
	<actipro:Badge Classes="accent" Kind="Dot" DotLength="20"
		HorizontalAlignment="Right" VerticalAlignment="Bottom" RenderTransform="translate(5px, 5px)" />
</Panel>

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:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...

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

<!-- Explicit 'Dot' kind even though content is available -->
<actipro: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, the default control template will set the padding based on the BadgeStringContentPadding theme resource. This theme resource is dynamically updated based on the current User Interface Density. See the Theme Generator topic for more details on customizing theme resources.

Themes and Semantic Color Variants

Badge controls in the outline, soft, and solid themes showing neutral and semantic color variants

The badge controls support the accent, success, warning, and danger style class names for semantic variants.

The following control themes are also supported:

• BadgeBase - Base control theme used by several others.
• BadgeOutline (theme-outline) - Has an outline appearance.
• BadgeSoft (theme-soft) - Has a soft fill appearance.
• BadgeSolid (theme-solid) - Has a solid appearance.

The following example demonstrates how to define a badge using the outline theme and danger variant:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:Badge Classes="theme-outline danger" />

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.

Pseudo-classes

The following pseudo-classes are available and can be used when styling the control:

Theme Resources

The following theme resources are available for customizing the appearance of the control: