Badge notifications for Windows apps

A notification badge conveys summary or status information specific to your app. They can be numeric (1-99) or one of a set of system-provided glyphs. Examples of information best conveyed through a badge include network connection status in an online game, user status in a messaging app, number of unread mails in a mail app, and number of new posts in a social media app.

Notification badges appear on your app's taskbar icon and in the lower-right corner of its start tile, regardless of whether the app is running. Badges can be displayed on all tile sizes.

Note

You cannot provide your own badge image; only system-provided badge images can be used.

Numeric badges

Value	Badge	XML
A number from 1 to 99. A value of 0 is equivalent to the glyph value "none" and will clear the badge.		<badge value="1"/>
Any number greater than 99.		<badge value="100"/>

Glyph badges

Instead of a number, a badge can display one of a non-extensible set of status glyphs.

Status	Glyph	XML
none	(No badge shown.)	<badge value="none"/>
activity		<badge value="activity"/>
alarm		<badge value="alarm"/>
alert		<badge value="alert"/>
attention		<badge value="attention"/>
available		<badge value="available"/>
away		<badge value="away"/>
busy		<badge value="busy"/>
error		<badge value="error"/>
newMessage		<badge value="newMessage"/>
paused		<badge value="paused"/>
playing		<badge value="playing"/>
unavailable		<badge value="unavailable"/>

Set a badge in a Windows App SDK app

Starting in Windows App SDK 1.7, use the BadgeNotificationManager class in the Microsoft.Windows.BadgeNotifications namespace to set and clear badges. This is the recommended approach for Windows App SDK apps. Instead of building an XML payload, you call a method and pass a number or a BadgeNotificationGlyph value.

• Important APIs: BadgeNotificationManager class, BadgeNotificationGlyph enum

Open the WinUI 3 Gallery app and see the BadgeNotificationManager in action

The WinUI 3 Gallery app includes interactive examples of WinUI controls and features. Get the app from the Microsoft Store or browse the source code on GitHub.

Important

BadgeNotificationManager requires package identity. If your app doesn't have package identity, for example because it's unpackaged, calls to SetBadgeAsCount, SetBadgeAsGlyph, and ClearBadge throw an exception. For more info, see An overview of Package Identity in Windows apps.

The badge appears on your app's taskbar icon. If the app is pinned to the taskbar, the badge appears even when the app isn't running. To get the BadgeNotificationManager instance for your app, use the Current property.

The following examples are based on the WinUI 3 Gallery sample. To use them, add a using Microsoft.Windows.BadgeNotifications; directive to your code file.

Set a numeric badge

Call SetBadgeAsCount and pass the number to show. If the number is greater than 99, the badge shows "99+".

private void SetBadgeCountButton_Click(object sender, RoutedEventArgs e)
{
    // Show the number 5 on the app's taskbar icon.
    BadgeNotificationManager.Current.SetBadgeAsCount(5);
}

Set a glyph badge

Call SetBadgeAsGlyph and pass a BadgeNotificationGlyph value. The enumeration values correspond to the glyphs in the Glyph badges table.

private void SetBadgeGlyphButton_Click(object sender, RoutedEventArgs e)
{
    // Show the alert glyph on the app's taskbar icon.
    BadgeNotificationManager.Current.SetBadgeAsGlyph(BadgeNotificationGlyph.Alert);
}

Clear the badge

Call ClearBadge to remove the badge. Setting a count of 0, or the BadgeNotificationGlyph.None glyph, also clears the badge.

private void ClearBadgeButton_Click(object sender, RoutedEventArgs e)
{
    BadgeNotificationManager.Current.ClearBadge();
}

Create a badge with the UWP BadgeUpdateManager API

These examples use the BadgeUpdateManager class in the Windows Runtime Windows.UI.Notifications namespace, which is the badge API for UWP apps. You build the badge as an XML payload, using the values in the previous tables. If your app uses Windows App SDK 1.7 or later, use BadgeNotificationManager instead.

Create a numeric badge

private void setBadgeNumber(int num)
{

    // Get the blank badge XML payload for a badge number
    XmlDocument badgeXml = 
        BadgeUpdateManager.GetTemplateContent(BadgeTemplateType.BadgeNumber);

    // Set the value of the badge in the XML to our number
    XmlElement badgeElement = badgeXml.SelectSingleNode("/badge") as XmlElement;
    badgeElement.SetAttribute("value", num.ToString());

    // Create the badge notification
    BadgeNotification badge = new BadgeNotification(badgeXml);

    // Create the badge updater for the application
    BadgeUpdater badgeUpdater = 
        BadgeUpdateManager.CreateBadgeUpdaterForApplication();

    // And update the badge
    badgeUpdater.Update(badge);

}

Create a glyph badge

private void updateBadgeGlyph()
{
    string badgeGlyphValue = "alert";

    // Get the blank badge XML payload for a badge glyph
    XmlDocument badgeXml = 
        BadgeUpdateManager.GetTemplateContent(BadgeTemplateType.BadgeGlyph);

    // Set the value of the badge in the XML to our glyph value
    Windows.Data.Xml.Dom.XmlElement badgeElement = 
        badgeXml.SelectSingleNode("/badge") as Windows.Data.Xml.Dom.XmlElement;
    badgeElement.SetAttribute("value", badgeGlyphValue);

    // Create the badge notification
    BadgeNotification badge = new BadgeNotification(badgeXml);

    // Create the badge updater for the application
    BadgeUpdater badgeUpdater = 
        BadgeUpdateManager.CreateBadgeUpdaterForApplication();

    // And update the badge
    badgeUpdater.Update(badge);

}

Clear a badge

private void clearBadge()
{
    BadgeUpdateManager.CreateBadgeUpdaterForApplication().Clear();
}

Get the sample code

• Windows App SDK notifications sample
  Shows how to send app notifications and badge updates.

Related articles

• App notification content
• Info badge
• BadgeNotificationManager class
• Create tiles
• Create adaptive tiles