Adding message dialogs (HTML)

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

A message dialog is an explicitly dismissed surface available to app developers to elicit an immediate response from the user. These dialogs dim the screen behind them and block touch events from passing to the app's canvas until the user responds.

A message dialog uses text and buttons, specified by the app developer, to do one of the following:

  • Convey urgent information.
  • Present an error message.
  • Ask a question that the user must answer to eliminate a blocking of the core flow of an application.
A message dialog can be in response to user action, or prompted by the app based on the state of the app.

Message dialogs should be used thoughtfully and sparingly, and only if the message to be conveyed is critical at that moment for the app. Message dialogs should be used only by Windows Store apps, not Windows desktop applications.

The following picture shows the three parts of a message dialog:

  • Title (optional)—used as the main instruction.
  • Content (required)—used as descriptive text.
  • Buttons and button strings (required)—to indicate the explicit user action.

Message dialog example

Message dialogs appear edge-to-edge across the app's canvas. Here's an example that shows a connectivity error. The dialog uses just the content text to convey the message.

Message dialog example

Here's an example that shows a network path error prompted by the file picker. This dialog uses the title string and the content text to convey the message.

Message dialog example

Note  The goal of the message dialog is not to replace all the uses of task dialogs and message box dialogs in previous Windows Windows desktop applications. The MessageDialog API is designed to be used by Windows Store apps only. For guidance on scenarios where message dialogs should be used, see Appropriate use of message dialogs.

In this section


Quickstart: Design a message dialog

This quickstart presents guidance on the design and implementation of message dialogs.