App notification content schema

The following describes all of the properties and elements within toast content.

If you would rather use raw XML instead of the Windows App SDK builder APIs, please see the XML schema.

ToastContent

• ToastVisual
  • ToastBindingGeneric
    • IToastBindingGenericChild
    • ToastGenericAppLogo
    • ToastGenericHeroImage
    • ToastGenericAttributionText
• IToastActions
• ToastAudio
• ToastHeader

ToastContent

ToastContent is the top level object that describes a notification's content, including visuals, actions, and audio.

Property	Type	Required	Description
Launch	string	false	A string that is passed to the application when it is activated by the Toast. 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.
Visual	ToastVisual	true	Describes the visual portion of the app notification.
Actions	IToastActions	false	Optionally create custom actions with buttons and inputs.
Audio	ToastAudio	false	Describes the audio portion of the app notification.
ActivationType	ToastActivationType	false	Specifies what activation type will be used when the user clicks the body of this Toast.
ActivationOptions	ToastActivationOptions	false	Additional options relating to activation of the app notification.
Scenario	ToastScenario	false	Declares the scenario your toast is used for, like an alarm or reminder.
DisplayTimestamp	DateTimeOffset?	false	Override the default timestamp with a custom timestamp representing when your notification content was actually delivered, rather than the time the notification was received by the Windows platform.
Header	ToastHeader	false	Add a custom header to your notification to group multiple notifications together within Notification Center.

ToastScenario

Specifies what scenario the toast represents.

Value	Meaning
Default	The normal toast behavior.
Reminder	A reminder notification. This will be displayed pre-expanded and stay on the user's screen till dismissed.
Alarm	An alarm notification. This will be displayed pre-expanded and stay on the user's screen till dismissed. Audio will loop by default and will use alarm audio.
IncomingCall	An incoming call notification. This will be displayed pre-expanded in a special call format and stay on the user's screen till dismissed. Audio will loop by default and will use ringtone audio.

ToastVisual

The visual portion of toasts contains the bindings, which contains text, images, adaptive content, and more.

Property	Type	Required	Description
BindingGeneric	ToastBindingGeneric	true	The generic toast binding, which can be rendered on all devices. This binding is required and cannot be null.
BaseUri	Uri	false	A default base URL that is combined with relative URLs in image source attributes.
AddImageQuery	bool?	false	Set to "true" to allow Windows to append a query string to the image URL supplied in the app notification. Use this attribute if your server hosts images and can handle query strings, either by retrieving an image variant based on the query strings or by ignoring the query string and returning the image as specified without the query string. This query string specifies scale, contrast setting, and language; for instance, a value of "www.website.com/images/hello.png" given in the notification becomes "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"
Language	string	false	The target locale of the visual payload when using localized resources, specified as BCP-47 language tags such as "en-US" or "fr-FR". This locale is overridden by any locale specified in binding or text. If not provided, the system locale will be used instead.

ToastBindingGeneric

The generic binding is the default binding for toasts, and is where you specify the text, images, adaptive content, and more.

Property	Type	Required	Description
Children	IList<IToastBindingGenericChild>	false	The contents of the body of the Toast, which can include text, images, and groups. Text elements must come before any other elements, and only 3 text elements are supported. If a text element is placed after any other element, it will either be pulled to the top or dropped. And finally, certain text properties like HintStyle aren't supported on the root children text elements, and only work inside an AdaptiveSubgroup.
AppLogoOverride	ToastGenericAppLogo	false	An optional logo to override the app logo.
HeroImage	ToastGenericHeroImage	false	An optional featured "hero" image that is displayed on the toast and within Notification Center.
Attribution	ToastGenericAttributionText	false	Optional attribution text which will be displayed at the bottom of the app notification.
BaseUri	Uri	false	A default base URL that is combined with relative URLs in image source attributes.
AddImageQuery	bool?	false	Set to "true" to allow Windows to append a query string to the image URL supplied in the app notification. Use this attribute if your server hosts images and can handle query strings, either by retrieving an image variant based on the query strings or by ignoring the query string and returning the image as specified without the query string. This query string specifies scale, contrast setting, and language; for instance, a value of "www.website.com/images/hello.png" given in the notification becomes "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"
Language	string	false	The target locale of the visual payload when using localized resources, specified as BCP-47 language tags such as "en-US" or "fr-FR". This locale is overridden by any locale specified in binding or text. If not provided, the system locale will be used instead.

IToastBindingGenericChild

Marker interface for toast child elements that include text, images, groups, and more.

Implementations
AdaptiveText
AdaptiveImage
AdaptiveGroup
AdaptiveProgressBar

AdaptiveText

An adaptive text element. If placed in the top level ToastBindingGeneric.Children, only HintMaxLines will be applied. But if this is placed as a child of a group/subgroup, full text styling is supported.

Property	Type	Required	Description
Text	string or BindableString	false	The text to display. Data binding only works for top-level text elements.
HintStyle	AdaptiveTextStyle	false	The style controls the text's font size, weight, and opacity. Only works for text elements inside a group/subgroup.
HintWrap	bool?	false	Set this to true to enable text wrapping. Top-level text elements ignore this property and always wrap (you can use HintMaxLines = 1 to disable wrapping for top-level text elements). Text elements inside groups/subgroups default to false for wrapping.
HintMaxLines	int?	false	The maximum number of lines the text element is allowed to display.
HintMinLines	int?	false	The minimum number of lines the text element must display. Only works for text elements inside a group/subgroup.
HintAlign	AdaptiveTextAlign	false	The horizontal alignment of the text. Only works for text elements inside a group/subgroup.
Language	string	false	The target locale of the XML payload, specified as a BCP-47 language tags such as "en-US" or "fr-FR". The locale specified here overrides any other specified locale, such as that in binding or visual. If this value is a literal string, this attribute defaults to the user's UI language. If this value is a string reference, this attribute defaults to the locale chosen by Windows Runtime in resolving the string.

BindableString

A binding value for strings.

Property	Type	Required	Description
BindingName	string	true	Gets or sets the name that maps to your binding data value.

AdaptiveTextStyle

Text style controls font size, weight, and opacity. Subtle opacity is 60% opaque.

Value	Meaning
Default	Default value. Style is determined by the renderer.
Caption	Smaller than paragraph font size.
CaptionSubtle	Same as Caption but with subtle opacity.
Body	Paragraph font size.
BodySubtle	Same as Body but with subtle opacity.
Base	Paragraph font size, bold weight. Essentially the bold version of Body.
BaseSubtle	Same as Base but with subtle opacity.
Subtitle	H4 font size.
SubtitleSubtle	Same as Subtitle but with subtle opacity.
Title	H3 font size.
TitleSubtle	Same as Title but with subtle opacity.
TitleNumeral	Same as Title but with top/bottom padding removed.
Subheader	H2 font size.
SubheaderSubtle	Same as Subheader but with subtle opacity.
SubheaderNumeral	Same as Subheader but with top/bottom padding removed.
Header	H1 font size.
HeaderSubtle	Same as Header but with subtle opacity.
HeaderNumeral	Same as Header but with top/bottom padding removed.

AdaptiveTextAlign

Controls the horizontal alignment of text.

Value	Meaning
Default	Default value. Alignment is automatically determined by the renderer.
Auto	Alignment determined by the current language and culture.
Left	Horizontally align the text to the left.
Center	Horizontally align the text in the center.
Right	Horizontally align the text to the right.

AdaptiveImage

An inline image.

Property	Type	Required	Description
Source	string	true	The URL to the image. ms-appx, ms-appdata, and http are supported. Web images can be up to 3 MB on normal connections and 1 MB on metered connections.
HintCrop	AdaptiveImageCrop	false	Control the desired cropping of the image.
HintRemoveMargin	bool?	false	By default, images inside groups/subgroups have an 8px margin around them. You can remove this margin by setting this property to true.
HintAlign	AdaptiveImageAlign	false	The horizontal alignment of the image. Only works for images inside a group/subgroup.
AlternateText	string	false	Alternate text describing the image, used for accessibility purposes.
AddImageQuery	bool?	false	Set to "true" to allow Windows to append a query string to the image URL supplied in the app notification. Use this attribute if your server hosts images and can handle query strings, either by retrieving an image variant based on the query strings or by ignoring the query string and returning the image as specified without the query string. This query string specifies scale, contrast setting, and language; for instance, a value of "www.website.com/images/hello.png" given in the notification becomes "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"

AdaptiveImageCrop

Specifies the desired cropping of the image.

Value	Meaning
Default	Default value. Cropping behavior determined by renderer.
None	Image is not cropped.
Circle	Image is cropped to a circle shape.

AdaptiveImageAlign

Specifies the horizontal alignment for an image.

Value	Meaning
Default	Default value. Alignment behavior determined by renderer.
Stretch	Image stretches to fill available width (and potentially available height too, depending on where the image is placed).
Left	Align the image to the left, displaying the image at its native resolution.
Center	Align the image in the center horizontally, displaying the image at its native resolution.
Right	Align the image to the right, displaying the image at its native resolution.

AdaptiveGroup

Groups semantically identify that the content in the group must either be displayed as a whole, or not displayed if it cannot fit. Groups also allow creating multiple columns.

Property	Type	Required	Description
Children	IList<AdaptiveSubgroup>	false	Subgroups are displayed as vertical columns. You must use subgroups to provide any content inside an AdaptiveGroup.

AdaptiveSubgroup

Subgroups are vertical columns that can contain text and images.

Property	Type	Required	Description
Children	IList<IAdaptiveSubgroupChild>	false	AdaptiveText and AdaptiveImage are valid children of subgroups.
HintWeight	int?	false	Control the width of this subgroup column by specifying the weight, relative to the other subgroups.
HintTextStacking	AdaptiveSubgroupTextStacking	false	Control the vertical alignment of this subgroup's content.

IAdaptiveSubgroupChild

Marker interface for subgroup children.

Implementations
AdaptiveText
AdaptiveImage

AdaptiveSubgroupTextStacking

TextStacking specifies the vertical alignment of content.

Value	Meaning
Default	Default value. Renderer automatically selects the default vertical alignment.
Top	Vertical align to the top.
Center	Vertical align to the center.
Bottom	Vertical align to the bottom.

AdaptiveProgressBar

A progress bar. Only supported on Desktop.

Property	Type	Required	Description
Title	string or BindableString	false	Gets or sets an optional title string. Supports data binding.
Value	double or AdaptiveProgressBarValue or BindableProgressBarValue	false	Gets or sets the value of the progress bar. Supports data binding. Defaults to 0.
ValueStringOverride	string or BindableString	false	Gets or sets an optional string to be displayed instead of the default percentage string. If this isn't provided, something like "70%" will be displayed.
Status	string or BindableString	true	Gets or sets a status string (required), which is displayed underneath the progress bar on the left. This string should reflect the status of the operation, like "Downloading..." or "Installing..."

AdaptiveProgressBarValue

A class that represents the progress bar's value.

Property	Type	Required	Description
Value	double	false	Gets or sets the value (0.0 - 1.0) representing the percent complete.
IsIndeterminate	bool	false	Gets or sets a value indicating whether the progress bar is indeterminate. If this is true, Value will be ignored.

BindableProgressBarValue

A bindable progress bar value.

Property	Type	Required	Description
BindingName	string	true	Gets or sets the name that maps to your binding data value.

ToastGenericAppLogo

A logo to be displayed instead of the app logo.

Property	Type	Required	Description
Source	string	true	The URL to the image. ms-appx, ms-appdata, and http are supported. Http images must be 200 KB or less in size.
HintCrop	ToastGenericAppLogoCrop	false	Specify how you would like the image to be cropped.
AlternateText	string	false	Alternate text describing the image, used for accessibility purposes.
AddImageQuery	bool?	false	Set to "true" to allow Windows to append a query string to the image URL supplied in the app notification. Use this attribute if your server hosts images and can handle query strings, either by retrieving an image variant based on the query strings or by ignoring the query string and returning the image as specified without the query string. This query string specifies scale, contrast setting, and language; for instance, a value of "www.website.com/images/hello.png" given in the notification becomes "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"

ToastGenericAppLogoCrop

Controls the cropping of the app logo image.

Value	Meaning
Default	Cropping uses the default behavior of the renderer.
None	Image is not cropped, displayed square.
Circle	Image is cropped to a circle.

ToastGenericHeroImage

A featured "hero" image that is displayed on the toast and within Notification Center.

Property	Type	Required	Description
Source	string	true	The URL to the image. ms-appx, ms-appdata, and http are supported. Http images must be 200 KB or less in size.
AlternateText	string	false	Alternate text describing the image, used for accessibility purposes.
AddImageQuery	bool?	false	Set to "true" to allow Windows to append a query string to the image URL supplied in the app notification. Use this attribute if your server hosts images and can handle query strings, either by retrieving an image variant based on the query strings or by ignoring the query string and returning the image as specified without the query string. This query string specifies scale, contrast setting, and language; for instance, a value of "www.website.com/images/hello.png" given in the notification becomes "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"

ToastGenericAttributionText

Attribution text displayed at the bottom of the app notification.

Property	Type	Required	Description
Text	string	true	The text to display.
Language	string	false	The target locale of the visual payload when using localized resources, specified as BCP-47 language tags such as "en-US" or "fr-FR". If not provided, the system locale will be used instead.

IToastActions

Marker interface for toast actions/inputs.

Implementations
ToastActionsCustom
ToastActionsSnoozeAndDismiss

ToastActionsCustom

Implements IToastActions

Create your own custom actions and inputs, using controls like buttons, text boxes, and selection inputs.

Property	Type	Required	Description
Inputs	IList<IToastInput>	false	Inputs like text boxes and selection inputs. Only up to 5 inputs are allowed.
Buttons	IList<IToastButton>	false	Buttons are displayed after all the inputs (or adjacent to an input if the button is used as a quick reply button). Only up to 5 buttons are allowed (or fewer if you also have context menu items).
ContextMenuItems	IList<ToastContextMenuItem>	false	Custom context menu items, providing additional actions if the user right clicks the notification. You can only have up to 5 buttons and context menu items combined.

IToastInput

Marker interface for toast inputs.

Implementations
ToastTextBox
ToastSelectionBox

ToastTextBox

Implements IToastInput

A text box control that the user can type text into.

Property	Type	Required	Description
Id	string	true	The Id is required, and is used to map the user-inputted text into a key-value pair of id/value which your app later consumes.
Title	string	false	Title text to display above the text box.
PlaceholderContent	string	false	Placeholder text to be displayed on the text box when the user hasn't typed any text yet.
DefaultInput	string	false	The initial text to place in the text box. Leave this null for a blank text box.

ToastSelectionBox

Implements IToastInput

A selection box control, which lets users pick from a dropdown list of options.

Property	Type	Required	Description
Id	string	true	The Id is required. If the user selected this item, this Id will be passed back to your app's code, representing which selection they chose.
Content	string	true	Content is required, and is a string that is displayed on the selection item.

ToastSelectionBoxItem

A selection box item (an item that the user can select from the drop down list).

Property	Type	Required	Description
Id	string	true	The Id is required, and is used to map the user-inputted text into a key-value pair of id/value which your app later consumes.
Title	string	false	Title text to display above the selection box.
DefaultSelectionBoxItemId	string	false	This controls which item is selected by default, and refers to the Id property of the ToastSelectionBoxItem. If you do not provide this, the default selection will be empty (user sees nothing).
Items	IList<ToastSelectionBoxItem>	false	The selection items that the user can pick from in this SelectionBox. Only 5 items can be added.

IToastButton

Marker interface for toast buttons.

Implementations
ToastButton
ToastButtonSnooze
ToastButtonDismiss

ToastButton

Implements IToastButton

A button that the user can click.

Property	Type	Required	Description
Content	string	true	Required. The text to display on the button.
Arguments	string	true	Required. App-defined string of arguments that the app will later receive if the user clicks this button.
ActivationType	ToastActivationType	false	Controls what type of activation this button will use when clicked. Defaults to Foreground.
ActivationOptions	ToastActivationOptions	false	Gets or sets additional options relating to activation of the toast button.

ToastActivationType

Decides the type of activation that will be used when the user interacts with a specific action.

Value	Meaning
Foreground	Default value. Your foreground app is launched.
Background	Your corresponding background task (assuming you set everything up) is triggered, and you can execute code in the background (like sending the user's quick reply message) without interrupting the user.
Protocol	Launch a different app using protocol activation.

ToastActivationOptions

Additional options relating to activation.

Property	Type	Required	Description
AfterActivationBehavior	ToastAfterActivationBehavior	false	Gets or sets the behavior that the toast should use when the user invokes this action. This only works on Desktop, for ToastButton and ToastContextMenuItem.
ProtocolActivationTargetApplicationPfn	string	false	If you are using ToastActivationType.Protocol, you can optionally specify the target PFN, so that regardless of whether multiple apps are registered to handle the same protocol uri, your desired app will always be launched.

ToastAfterActivationBehavior

Specifies the behavior that the toast should use when the user takes action on the toast.

Value	Meaning
Default	Default behavior. The toast will be dismissed when the user takes action on the toast.
PendingUpdate	After the user clicks a button on your toast, the notification will remain present, in a "pending update" visual state. You should immediately update your toast from a background task so that the user does not see this "pending update" visual state for too long.

ToastButtonSnooze

Implements IToastButton

A system-handled snooze button that automatically handles snoozing of the notification.

Property	Type	Required	Description
CustomContent	string	false	Optional custom text displayed on the button that overrides the default localized "Snooze" text.

ToastButtonDismiss

Implements IToastButton

A system-handled dismiss button that dismisses the notification when clicked.

Property	Type	Required	Description
CustomContent	string	false	Optional custom text displayed on the button that overrides the default localized "Dismiss" text.

ToastActionsSnoozeAndDismiss

*Implements IToastActions

Automatically constructs a selection box for snooze intervals, and snooze/dismiss buttons, all automatically localized, and snoozing logic is automatically handled by the system.

Property	Type	Required	Description
ContextMenuItems	IList<ToastContextMenuItem>	false	Custom context menu items, providing additional actions if the user right clicks the notification. You can only have up to 5 items.

ToastContextMenuItem

A context menu item entry.

Property	Type	Required	Description
Content	string	true	Required. The text to display.
Arguments	string	true	Required. App-defined string of arguments that the app can later retrieve once it is activated when the user clicks the menu item.
ActivationType	ToastActivationType	false	Controls what type of activation this menu item will use when clicked. Defaults to Foreground.
ActivationOptions	ToastActivationOptions	false	Additional options relating to activation of the toast context menu item.

ToastAudio

Specify audio to be played when the app notification is received.

Property	Type	Required	Description
Src	uri	false	The media file to play in place of the default sound. Only ms-appx and ms-resource are supported. All else (ms-appdata, http, C:, etc.) is not supported.
Loop	boolean	false	Set to true if the sound should repeat as long as the Toast is shown; false to play only once (default).
Silent	boolean	false	True to mute the sound; false to allow the app notification sound to play (default).

ToastHeader

A custom header that groups multiple notifications together within Notification Center.

Property	Type	Required	Description
Id	string	true	A developer-created identifier that uniquely identifies this header. If two notifications have the same header id, they will be displayed underneath the same header in Notification Center.
Title	string	true	A title for the header.
Arguments	string	true	Gets or sets a developer-defined string of arguments that is returned to the app when the user clicks this header. Cannot be null.
ActivationType	ToastActivationType	false	Gets or sets the type of activation this header will use when clicked. Defaults to Foreground. Note that only Foreground and Protocol are supported.
ActivationOptions	ToastActivationOptions	false	Gets or sets additional options relating to activation of the toast header.

Related topics

• Quickstart: Send a local toast and handle activation