InAppNotification

Article
09/23/2021

The InAppNotification control offers the ability to show local notifications in your application.

The control should be placed where you want your notification to be displayed in the page, generally in the root grid.

Note

Since the control is part of the page visual tree, it will render in the order it was added in the parent control, and might be hidden by other elements. For the control to render on top of other elements, add it as the last child of the parent control or set the Canvas.ZIndex to a high number.

Try it in the sample app

Syntax

<controls:InAppNotification>
    <!-- InAppNotification content -->
</controls:InAppNotification>

Sample Output

InAppNotification animation

Properties

Property	Type	Description
AnimationDuration	TimeSpan	Gets or sets a value indicating the duration of the popup animation (in milliseconds)
HorizontalOffset	double	Gets or sets a value indicating the horizontal offset of the popup animation
ShowDismissButton	bool	Gets or sets a value indicating whether to show the Dismiss button of the control
StackMode	StackMode	Gets or sets a value indicating the stack mode of the notifications
VerticalOffset	double	Gets or sets a value indicating the vertical offset of the popup animation

StackMode

By default, each time you display an in-app notification using the same control, each notification will replace the previous one. You can change this behavior with one of these values:

StackMode properties	Description
Replace	Default mode, replace previous notification
QueueBehind	Store every notifications to show, when you dismiss a notification the remaining ones will be displayed successively
StackInFront	Store every notifications to show, when you show a notification it will be displayed in priority (in the reverse order of `QueueBehind` mode)

Methods

Methods	Return Type	Description
Dismiss()	void	Dismiss the notification
Show(int)	void	Show notification using the current template
Show(String, int)	void	Show notification using text as the content of the notification with a display duration
Show(DataTemplate, int)	void	Show notification using DataTemplate as the content of the notification with a display duration
Show(UIElement, int)	void	Show notification using UIElement as the content of the notification with a display duration
Show(object, int)	void	Show notification using object as the content of the notification with a display duration. Object will be displayed using the `InAppNotification.ContentTemplate` data template.

Events

Events	Description
Closed	Event raised when the notification is closed
Closing	Event raised when the notification is closing
Opened	Event raised when the notification is opened
Opening	Event raised when the notification is opening

Examples

You have multiple options to show an in-app notification.

By simply displaying the notification using the current template

ExampleInAppNotification.Show();

ExampleInAppNotification.Show()

By using a simple text content.

ExampleInAppNotification.Show("Some text.");

ExampleInAppNotification.Show("Some text.")

By using a UIElement (with a container as parent, ex: Grid)

var grid = new Grid();

// TODO : Construct the Grid in C#
ExampleInAppNotification.Show(grid);

Dim grid = New Grid()

' TODO : Construct the Grid in code
ExampleInAppNotification.Show(grid)

By using a DataTemplate

object inAppNotificationWithButtonsTemplate;
bool isTemplatePresent = Resources.TryGetValue("InAppNotificationWithButtonsTemplate", out inAppNotificationWithButtonsTemplate);

if (isTemplatePresent && inAppNotificationWithButtonsTemplate is DataTemplate)
{
    ExampleInAppNotification.Show(inAppNotificationWithButtonsTemplate as DataTemplate);
}

Dim inAppNotificationWithButtonsTemplate As Object
Dim isTemplatePresent As Boolean = Resources.TryGetValue("InAppNotificationWithButtonsTemplate", inAppNotificationWithButtonsTemplate)

If isTemplatePresent AndAlso TypeOf inAppNotificationWithButtonsTemplate Is DataTemplate Then
    ExampleInAppNotification.Show(TryCast(inAppNotificationWithButtonsTemplate, DataTemplate))
End If

By using a DataTemplate and an object

<controls:InAppNotification
    x:Name="ExampleInAppNotification"
    ContentTemplate="{StaticResource MyNotificationDataTemplate}" />

var notificationData = new MyNotificationData("Title", "Message");
ExampleInAppNotification.Show(notificationData, duration: 2000);

Dim notificationData As New MyNotificationData("Title", "Message");
ExampleInAppNotification.Show(notificationData, duration: 2000);

By passing a second argument to the Show() method, you can set the duration of the notification (in milliseconds).

ExampleInAppNotification.Show("Some text.", 2000); // the notification will appear for 2 seconds

ExampleInAppNotification.Show("Some text.", 2000)  ' The notification will appear for 2 seconds

Call Dismiss to dismiss the notification

ExampleInAppNotification.Dismiss();

ExampleInAppNotification.Dismiss()

Use EventArgs to find the dismiss kind of the InAppNotification in and Closed

private void InAppNotification_OnClosing(object sender, InAppNotificationDismissingEventArgs e)
{
    if (e.DismissKind == InAppNotificationDismissKind.User)
    {
        // When the user asked to dismiss the notification
    }
    if (e.DismissKind == InAppNotificationDismissKind.Timeout)
    {
        // When the notification is dismissed after timeout
    }
}

Private Sub InAppNotification_OnClosing(ByVal sender As Object, ByVal e As InAppNotificationDismissingEventArgs)
    If e.DismissKind = InAppNotificationDismissKind.User Then
        ' When the user asked to dismiss the notification
    End If

    If e.DismissKind = InAppNotificationDismissKind.Timeout Then
        ' When the notification is dismissed after timeout
    End If
End Sub

The in-app notification control is designed to support multiple styles. The default style applied is the Microsoft Edge-like notification. Other styles have been added to the Toolkit so you can easily switch to another of your favorite In App Notification styles.

Here is the list of existing styles :
- Microsoft Edge notification style
- Visual Studio Code notification style
  
  If you want to use another style than the default one, please follow the example below :
- Import external styles in your resources
```
<Page.Resources>
  <ResourceDictionary>
      <ResourceDictionary.MergedDictionaries>
          <ResourceDictionary Source="ms-appx:///Microsoft.Toolkit.Uwp.UI.Controls/InAppNotification/Styles/VSCodeNotificationStyle.xaml" />
      </ResourceDictionary.MergedDictionaries>
  </ResourceDictionary>
</Page.Resources>
```
- Apply the Style
```
<controls:InAppNotification 
  x:Name="ExampleVSCodeInAppNotification"
  Style="{StaticResource VSCodeNotificationStyle}" />
```

Adding styles to Toolkit

If you want to add styles to the Toolkit, please follow these steps :

Create a ResourceDictionary file in Microsoft.Toolkit.Uwp.UI.Controls/InAppNotification/Styles/ folder
Create a new Style with TargetType="local:InAppNotification"
Create a new ControlTemplate with TargetType="local:InAppNotification" and add a ContentPresenter inside the Template
Do not forget to set the Template property inside your Style resource

Sample Project

InAppNotification Sample Page Source. You can see this in action in the Windows Community Toolkit Sample App.

Default Template

InAppNotification XAML File is the XAML template used in the toolkit for the default styling.

Requirements

Device family	Universal, 10.0.16299.0 or higher
Namespace	Microsoft.Toolkit.Uwp.UI.Controls
NuGet package	Microsoft.Toolkit.Uwp.UI.Controls

API

InAppNotification source code