Archived: Adaptive and interactive toast notifications for Windows 10 (10586)


Archived: Click here to view the latest documentation.

Adaptive and interactive toast notifications are a new feature in Windows 10. They allow you to:

  • Create flexible toast notifications with more content and optional inline images without being limited to the previous “toast template catalog”.
  • Create interactive toast notifications that enable user interaction.

To see the legacy templates from Windows 8.1 and Windows Phone 8.1, please see the legacy toast template catalog.

Overview

In Windows 10, we have updated the existing toast templates in several aspects:

  • Moved from a restricted template model to a flexible and adaptive template model;
  • Added ability to include buttons/inputs;
  • Provided 3 different activation types for the main toast notification and for each action;
  • Added ability to create a notification for specific scenarios, including alarm, reminder, and incoming call.

All of the above will be covered in this post.

Structure of toast notification

In Windows 10, developers construct a toast notification using XML, which should typically contain the following key elements:

  • <visual> which covers the content available for the users to visually see, including text and images;
  • <actions> which contains buttons/inputs the developer wants to add inside the notification;
  • <audio> which specifies the sound played when the notification pops.

Here is a quick example:

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <text>Sample</text>
      <text>This is a simple toast notification example</text>
      <image placement="AppLogoOverride" src="oneAlarm.png" />
    </binding>
  </visual>
  <actions>
    <action content="check" arguments="check" imageUri="check.png" />
    <action content="cancel" arguments="cancel" />
  </actions>
  <audio src="ms-winsoundevent:Notification.Reminder"/>
</toast>

toast structure

Visual

Inside the visual element, you must have exactly one binding element, containing the visual contents of the toast.

Unlike tile notifications, which support multiple templates based on different tile sizes, toast notifications for Windows 10 UWP apps only have one template name – ToastGeneric. This has several advantages over the legacy template model which was a set of restricted templates.

  • Flexible. Developers can change the content of the toast, such as adding another line of text, adding an optional inline image, or change the thumbnail image from displaying the application icon to something else, without worrying about changing the entire template or creating an invalid payload due to template-name – content mismatch.
  • Adaptive. Developers can use the same code to construct the same payload for the toast notification that targets to deliver to different types of Windows devices, such as phone, tablet, desktop PC, or even Xbox – the different devices will accept the notification, and display it to the user under their own UI policies with appropriate visual affordance and interaction model.

For all the attributes supported in the visual section and its child elements, please see the Schema section below.

For more examples, please see Samples below.

Actions

In Windows 10 UWP apps, developers can add buttons/inputs to their toast notification, to empower the users to do more outside of the app. The actions are specified under the <actions> element. There are 2 types of elements a developer can specify:

  • <action>. This appears as a button on Desktop and Mobile. A developer can specify up to 5 custom or system actions inside a toast notification.
  • <input>. This allows users to provide input, like quick replying to a message or selecting an option from a drop down menu.

Note: Both <action> and <input> are adaptive within the Windows family. For example, in Windows Mobile or Desktop, an <action> to a user is a button to tap/click on. A text <input> is a textbox that user can input text with using keyboard or virtual keyboard. It is, however, very possible that in some future devices, an action is announced out by voice, and a text input from the user is taken by dictation – the notification’s interactivity will adapt to the interaction model and visual affordance of the device where the message is displayed on.

When an action is taken by the user, the developer can choose to do one of the following by specifying the activationType attribute inside <action>:

    • Activating the app in the foreground, with an action-specific argument that can be used to navigate to a specific page/context;
    • Activating the app’s background task without affecting the user;
    • Activating another app via protocol launch;
    • Specify a system action to perform. The current available system actions are snoozing and dismissing scheduled alarm/reminder, which will be further explained in a section below.

For all the attributes supported in <actions> section and its child elements, please see the Schema section below.

For an example of how interactive toasts work, please see the Samples below.

Audio

In Windows 10 UWP apps, the <audio> element remains unchanged compared to 8.1.

Mobile can use custom audio (ms-appx and ms-appdata), but Desktop cannot. Both can use ms-winsoundevent. For more info on toast audio, see the audio schema page.

Toast notifications for special scenarios

In Windows 10, a developer can use toast notifications for alarms, reminders, and incoming calls. These special toast notifications look visually consistent with the “standard” toast notifications, with some extra bits of UI policy that fits each scenario.

A reminder toast notification will stay on screen until the user dismisses it or takes action. On Windows Mobile, the reminder toast notifications will also show up pre-expanded.

In addition to sharing the above behaviors with reminder notifications, alarm notifications also automatically play looping audio.

Incoming call notifications are displayed full screen on Windows Mobile devices.

This is done by specifying the “scenario” attribute inside the root element of a toast notification – <toast>:

<toast scenario=” { default | alarm | reminder | incomingCall } ” >

XML Samples

Please note that all toast notification screenshots are taken from Desktop. The mobile version of the toast notifications are pre-collapsed depending on their scenario, with a grabber at the bottom to expand.

Notification with rich visual contents

You can have multiple lines of text, an optional small image to override the application logo, and an optional inline image thumbnail in a toast.

<toast launch="app-defined-string">
  <visual>
<binding template="ToastGeneric">
	<text>Photo Share</text>
      <text>Andrew sent you a picture</text>
      <text>See it in full size!</text>
      <image placement="appLogoOverride" src="A.png" />
	<image placement="inline" src="hiking.png" />
    </binding>
  </visual>
</toast>

toast structure

Notification with actions (sample 1)

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <text>Microsoft Company Store</text>
      <text>New Halo game is back in stock!</text>
      <image placement="appLogoOverride" src="A.png" />
    </binding>
  </visual>
  <actions>
    <action activationType="foreground" content="see more details" arguments="details" imageUri="check.png"/>
    <action activationType="background" content="remind me later" arguments="later" imageUri="cancel.png"/>
  </actions>
</toast>

toast structure

Notification with actions (sample 2)

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <text>Cortana</text>
      <text>We noticed that you are near Wasaki.</text>
      <text>Thomas left a 5 star rating after his last visit, do you want to try?</text>
      <image placement="appLogoOverride" src="A.png" />
    </binding>
  </visual>
  <actions>
    <action activationType="foreground" content="reviews" arguments="reviews" />
    <action activationType="protocol" content="show map" arguments="bingmaps:?q=sushi" />
  </actions>
</toast>

toast structure

Notification with text input and actions (sample 1)

In this sample, you can add a textbox that allows the user to input text.

<toast launch="developer-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <text>Andrew B.</text>
      <text>Shall we meet up at 8?</text>
      <image placement="appLogoOverride" src="A.png" />
    </binding>
  </visual>
  <actions>
    <input id="message" type="text" placeHolderContent="reply here" />
    <action activationType="background" content="reply" arguments="reply" />
    <action activationType="foreground" content="video call" arguments="video" />
  </actions>
</toast>

toast structure

Notification with text input and actions (sample 2)

If allowing user to reply with text input is the only scenario you care about, you can also use the below layout. This only works if your action specifies an image icon.

<toast launch="developer-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <text>Andrew B.</text>
      <text>Shall we meet up at 8?</text>
      <image placement="appLogoOverride" src="A.png" />
    </binding>
  </visual>
  <actions>
    <input id="message" type="text" placeHolderContent="reply here" />
    <action activationType="background" content="reply" arguments="reply" imageUri="send.png" hint-inputId="message"/>
  </actions>
</toast>

toast structure

Notification with selection input and actions

In this sample, you can add a dropdown list with pre-defined selections for the user to select.

<toast launch="developer-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <text>Spicy Heaven</text>
      <text>When do you plan to come in tomorrow?</text>
      <image placement="appLogoOverride" src="A.png" />
    </binding>
  </visual>
  <actions>
    <input id="time" type="selection" defaultInput="2" >
  <selection id="1" content="Breakfast" />
  <selection id="2" content="Lunch" />
  <selection id="3" content="Dinner" />
    </input>
    <action activationType="background" content="Reserve" arguments="reserve" />
    <action activationType="background" content="Call Restaurant" arguments="call" />
  </actions>
</toast>

toast structure

Reminder Notification

Note that in a reminder scenario, the image is enlarged to fill the width of the toast notification.

<toast scenario="reminder" launch="developer-pre-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <text>Adam's Hiking Camp</text>
      <text>You have an upcoming event for this Friday!</text>
      <text>RSVP before it"s too late.</text>
      <image placement="appLogoOverride" src="A.png" />
      <image placement="inline" src="hiking.png" />
    </binding>
  </visual>
  <actions>
    <action activationType="background" content="RSVP" arguments="rsvp" />
    <action activationType="background" content="Reminder me later" arguments="later" />
  </actions>
</toast>

toast structure

Handling foreground and background activation

To learn how to handle toast activations (the user clicking on your toast or buttons on the toast), see the Quicstart: Sending a local toast notifications and handling activations article.

Schema

Note: “?” means an attribute is optional

Section 1. <visual> and <audio>

<toast launch? duration? activationType? scenario? >
    <visual version? lang? baseUri? addImageQuery? >
        <binding template? lang? baseUri? addImageQuery? >
            <text lang? >content</text>
            <text />
            <image src placement? alt? addImageQuery? hint-crop? />
        </binding>
    </visual>
    <audio src? loop? silent? />
    <actions>
    </actions>
</toast>

Attributes in <toast>

launch?

launch? = string

This is an optional attribute.

A string that is passed to the application when it is activated by the toast. Depending on the value of activationType, this value can be received by the app in the foreground, inside the background task, or by another app that’s protocol launched from the original app.

The format and contents of this string are defined by the app for its own use. When the user taps or clicks the toast to launch its associated app, the launch string provides the context to the app that allows it to show the user a view relevant to the toast content, rather than launching in its default way.

[Note] If the activation is happened because user clicked on an action, instead of the body of the toast, the developer retrieves back the “arguments” pre-defined in that <action> tag, instead of “launch” pre-defined in the <toast> tag.

 

 

duration?

duration? = “short|long”

This is an optional attribute. Default value is “short”.

This attribute was introduced back in Windows 8 time-frame for specifying how long the toast notification stays on the screen – setting the value to “short” will make the notification display for  ~7 seconds and setting it to “long” will make the notification display for ~25 seconds. 

In Windows 10, developers have the following options to keep the notification on screen for longer than standard length (~7 seconds):

  • Specifying scenario attribute (see description below) to “alarm” or “reminder” to persist the notification on screen until the user dismisses it. 
  • Specify duration attribute to “long” while making sure the scenario attribute is specified to “default” or unspecified. This will result in the legacy behavior of notification showing on screen for ~25 seconds. 
    • We do not recommend using this property unless you have a good reason to keep the notification up for ~25 seconds on screen. This attribute exists mainly for appCompat reason. 

activationType?

activationType? = “foreground | background | protocol | system”

This is an optional attribute, default value is “foreground“.

scenario?

scenario? = “default | alarm | reminder | incomingCall”

This is an optional attribute, default value is “default”.

You do not need this unless your scenario is to pop an alarm, reminder, or incoming call. Do not use this just for keeping your notification persistent on screen.

Attributes in <visual>

version?

version? = nonNegativeInteger

You do NOT need this since we will be deprecating versioning on visual and come up with new versioning model that you specify from a higher hierarchy if needed.

lang?

Please see MSDN for details on these existing optional attributes.

baseUri?

Please see MSDN for details on these existing optional attributes.

addImageQuery?

Please see MSDN for details on these existing optional attributes.

 

Attributes in <binding>

template?

[Important] template? = “ToastGeneric”

If you are using any of the new adaptive and interactive notification features, please make sure you start using “ToastGeneric” template instead of the legacy template.

Using the legacy templates with the new actions might work now, but that is not the intended use case, and we cannot guarantee that will continue working.

lang?

Please see MSDN for details on these existing optional attributes.

baseUri?

Please see MSDN for details on these existing optional attributes.

addImageQuery?

Please see MSDN for details on these existing optional attributes.

 

Attributes in <text>

lang?

Please see MSDN for details on these existing optional attributes.

 

Attributes in <image>

src 

Please see MSDN

placement?

placement? = “inline” | “appLogoOverride”

This is optional.

This specifies where this image will be displayed.

“inline” means inside the toast body, below the text;

appLogoOverride” means replace the application icon (that shows up on the top left corner of the toast).

You can have up to 1 image for each placement value.

alt?

Please see MSDN.

addImageQuery?

Please see MSDN.

hint-crop?

hint-crop? = “none” | “circle”

This is optional.

none” is the default value which means no cropping.

circle” means cropping the image to a circular shape. Use this for profile images of a contact, image of a person, etc. as part of metro 2.0 design guidance.

 

Attributes in <audio>

src?

Please see MSDN.

loop?

Please see MSDN.

silent?

Please see MSDN.

Section 2. <actions>

<toast>
    <visual>
    </visual>
    <audio />
    <actions>
        <input id type title? placeHolderContent? defaultInput? >
            <selection id content />
        </input>
        <action content arguments activationType? imageUri? hint-inputId />
    </actions>
</toast>

Attributes in <input>

id

id = string

The id attribute is required and is used by developers to retrieve user inputs once the app is activated (in the foreground or background).

type

The type attribute is required.

type = “text | selection

It is used to specify a text input or input from a list of pre-defined selections.

On mobile and desktop, this is to specify whether you want a textbox input or a listbox input.

title?

title? = string

The title attribute is optional and is for developers to specify a title for the input for shells to render when there is affordance.

For mobile and desktop, this title will be displayed above the input.

placeHolderContent?

placeHolderContent? = string

The placeHolderContent attribute is optional and is the grey-out hint text for text input type. This attribute is ignored when the input type is not “text”.

defaultInput?

defaultInput? = string

The defaultInput attribute is optional and is used to provide a default input value.

If the input type is “text”, this will be treated as a string input;

If the input type is “selection”, this is expected to be the id of one of the available selections inside this input’s elements.

 

Attributes in <selection>

id

The id attribute is required. As a developer, you will use this id to identify which selection was selected by the user (the id is returned to your app).

content

The content attribute is required.

It provides the string to display for this selection element.

 

Attributes in <action>

content

content = string

The content attribute is required.

It provides the text string displayed on the button.

arguments

arguments = string

The arguments attribute describes the app-defined data that the app can later retrieve once it is activated from user taking this action.

activationType?

activationType? = “foreground | background | protocol | system
The activationType attribute is optional and the default value is “foreground”.

It describes what kind of activation this action will cause – foreground, background, or launching another app via protocol launch, or invoking a system action.

imageUri?

imageUri? = string

imageUri is optional and is used to provide an image icon for this action to display inside the button alone with the text content.

hint-inputId

hint-inputId = string

This is specifically used for the quick reply scenario.

The value needs to be the id of the input element desired to be associated with.

In mobile and desktop, this will put the button right next to the input box.

Section 3. Additional attributes for system handled actions.

In addition to the above sections, in Windows 10, we also provide system-handled actions for snoozing and dismissing notifications, for apps that do not want to handle the snoozing/rescheduling of these notifications inside their background task. The actions can be combined, or specified individually, but we do not recommend anyone implementing a snooze action without a dismiss action.

System commands combo – SnoozeAndDismiss

<toast>
    <visual>
    </visual>
    <audio />
    <actions hint-systemCommands? = "SnoozeAndDismiss" />
</toast>

Attributes in <actions>

hint-systemCommands?

WARNING: If you’re releasing a Mobile app, do NOT use this on TH1 and TH2 machines. hint-systemCommands is broken on Mobile and won’t allow the user to select a snooze time. Only use this if you’re only releasing your app on Desktop. If releasing an app on both, we recommend using the “Individual system handled actions” as seen below.

This has been fixed for Mobile RS1 builds 14273 and newer, and functions correctly.

This hint attribute will construct a dropbox for selecting snooze interval, a snooze action, and a dismiss action. The snooze and dismiss will all be handled by system (the app will not be activated when the user takes these actions).

The string displayed for the input and the 2 actions will be properly localized.

Individual system handled actions

<toast>
    <visual>
    </visual>
    <audio />
<actions>
<input id="snoozeTime" type="selection" defaultInput="10">
  <selection id="5" content="5 minutes" />
  <selection id="10" content="10 minutes" />
  <selection id="20" content="20 minutes" />
  <selection id="30" content="30 minutes" />
  <selection id="60" content="1 hour" />
</input>
<action activationType="system" arguments="snooze" hint-inputId="snoozeTime" content=""/>
<action activationType="system" arguments="dismiss" content=""/>
</actions>
</toast>

To construct individual snooze and dismiss actions, you need to do the following:

  • Specify activationType = “system”.
  • Specify arguments = “snooze” | “dismiss”
  • Specify content:
    • If you want localized string of “snooze” and “dismiss” to be displayed on the actions, then specify content to be empty string – <action content = “”/>;
    • If you want your own customized string, just provide its value – <action content=”Remind me later” />.
  • Specify input:
    • If you do NOT want user to select a snooze interval, instead, just want your notification to snooze only once for a system-defined time interval (that is consistent across the OS), then do NOT construct any <input> at all;
    • If you want to provide selections of snooze interval:
      • Specify hint-inputId in the snooze action;
      • Make sure you match the id of the input with the hint-inputId of the snooze action – <input id=”snoozeTime”></input><action hint-inputId=”snoozeTime”/>
      • Specify id for selection to be a nonNegativeInteger which represent snooze interval in minutes – <selection id=”240” /> means snoozing for 4 hours;
      • Make sure that the value of defaultInput in <input> matches with one of the ids of the <selection> children elements.
      • Provide up to (but no more than) 5 <selection> values.
Skip to main content