Getting started

Install Notifications library. If you'd like to use C# instead of XML to generate notifications, install the NuGet package named Microsoft.Toolkit.Uwp.Notifications (search for "notifications uwp"). The C# samples provided in this article use version 1.0.0 of the NuGet package.

Sending a toast notification

To learn how to send a notification, see Send local toast. This documentation only covers creating the toast content.

Toast notification structure

Toast notifications are a combination of some data properties like Tag/Group (which let you identify the notification) and the toast content.

The core components of toast content are...

launch: This defines what arguments will be passed back to your app when the user clicks your toast, allowing you to deep link into the correct content that the toast was displaying. To learn more, see Send local toast.

visual: The visual portion of the toast, including the generic binding that contains text and images.

actions: The interactive portion of the toast, including inputs and actions.

audio: Controls the audio played when the toast is shown to the user.

The toast content is defined in raw XML, but you can use our NuGet library to get a C# (or C++) object model for constructing the toast content. This article documents everything that goes within the toast content.

Visual

Each toast must specify a visual, where you must provide a generic toast binding, which can contain text, images, and more. These elements will be rendered on various Windows devices, including desktop, phones, tablets, and Xbox.

Your app's identity on the toast notification is conveyed via your app icon. However, if you use the app logo override, we will display your app name beneath your lines of text.

App identity for normal toast

App identity with appLogoOverride

Text elements

Each toast must have at least one text element, and can contain two additional text elements, all of type AdaptiveText.

Since the Windows 10 Anniversary Update, you can control how many lines of text are displayed by using the HintMaxLines property on the text. The default (and maximum) is up to 2 lines of text for the title, and up to 4 lines (combined) for the two additional description elements (the second and third AdaptiveText).

App logo override

By default, your toast will display your app's logo. However, you can override this logo with your own ToastGenericAppLogo image. For example, if this is a notification from a person, we recommend overriding the app logo with a picture of that person.

You can use the HintCrop property to change the cropping of the image. For example, Circle results in a circle-cropped image. Otherwise, the image is square. Image dimensions are 48x48 pixels at 100% scaling.

Hero image

New in Anniversary Update: Toasts can display a hero image, which is a featured ToastGenericHeroImage displayed prominently within the toast banner and while inside Action Center. Image dimensions are 364x180 pixels at 100% scaling.

Image size restrictions

The images you use in your toast notification can be sourced from...

http://

ms-appx:///

ms-appdata:///

For http and https remote web images, there are limits on the file size of each individual image. In the Fall Creators Update (16299), we increased the limit to be 3 MB on normal connections and 1 MB on metered connections. Before that, images were always limited to 200 KB.

Normal connection

Metered connection

Before Fall Creators Update

3 MB

1 MB

200 KB

If an image exceeds the file size, or fails to download, or times out, the image will be dropped and the rest of the notification will be displayed.

Attribution text

New in Anniversary Update: If you need to reference the source of your content, you can use attribution text. This text is always displayed at the bottom of your notification, along with your app's identity or the notification's timestamp.

On older versions of Windows that don't support attribution text, the text will simply be displayed as another text element (assuming you don't already have the maximum of three text elements).

Custom timestamp

New in Creators Update: You can now override the system-provided timestamp with your own timestamp that accurately represents when the message/information/content was generated. This timestamp is visible within Action Center.

Headers

New in Creators Update: You can group notifications under headers within Action Center. For example, you can group messages from a group chat under a header, or group notifications of a common theme under a header, or more.

Buttons

Buttons make your toast interactive, letting the user take quick actions on your toast notification without interrupting their current workflow. For example, users can reply to a message directly from within a toast, or delete an email without even opening the email app. Buttons appear in the expanded portion of your notification.

Buttons with icons

You can add icons to your buttons. These icons are white transparent 16x16 pixel images at 100% scaling, and should have no padding included in the image itself. If you choose to provide icons on a toast notification, you must provide icons for ALL of your buttons in the notification, as it transforms the style of your buttons into icon buttons.

Note

For accessibility, be sure to include a contrast-white version of the icon (a black icon for white backgrounds), so that when the user turns on High Contrast White mode, your icon is visible. Learn more on the toast accessiblity page.

Buttons with pending update activation

New in Fall Creators Update: On background activation buttons, you can use an after activation behavior of PendingUpdate to create multi-step interactions in your toast notifications. When the user clicks your button, your background task is activated, and the toast gets placed in a "pending update" state, where it stays on screen till your background task replaces the toast with a new toast.

Context menu actions

New in Anniversary Update: You can add additional context menu actions to the existing context menu that appears when the user right clicks your toast from within Action Center. Note that this menu only appears when right clicked from Action Center. It does not appear when right clicking a toast popup banner.

Snooze/dismiss

Using a selection menu and two buttons, we can create a reminder notification that utilizes the system snooze and dismiss actions. Make sure to set the scenario to Reminder for the notification to behave like a reminder.

We link the Snooze button to the selection menu input using the SelectionBoxId property on the toast button.

If you don't provide a string, we'll automatically use localized strings for "Snooze" and "Dismiss".

Optionally specify the SelectionBoxId:

If you don't want the user to select a snooze interval and instead just want your notification to snooze only once for a system-defined time interval (that is consistent across the OS), then don't construct any <input> at all.

If you want to provide snooze interval selections:

Specify SelectionBoxId in the snooze action

Match the id of the input with the SelectionBoxId of the snooze action

Specify ToastSelectionBoxItem's value to be a nonNegativeInteger which represents snooze interval in minutes.

Audio

Custom audio has always been supported by Mobile, and is supported in Desktop Version 1511 (build 10586) or newer. Custom audio can be referenced via the following paths:

Alarms, reminders, and incoming calls

To create alarms, reminders, and incoming call notifications, you simply use a normal toast notification with a scenario value assigned to it. The scenario adusts a few behaviors to create a consistent and unified user experience.

Important

When using Reminder or Alarm, you must provide at least one button on your toast notification. Otherwise, the toast will be treated as a normal toast.

Reminder: The notification will stay on screen until the user dismisses it or takes action. On Windows Mobile, the toast will also show pre-expanded. A reminder sound will be played.

Alarm: In addition to the reminder behaviors, alarms will additionally loop audio with a default alarm sound.

IncomingCall: Incoming call notifications are displayed full screen on Windows Mobile devices. Otherwise, they have the same behaviors as alarms except they use ringtone audio and their buttons are styled differently.