Guidelines for message dialogs

A sample of what a standard dialog control looks like


A message dialog is an overlay UI element that provides a stable and contextual surface that is always modal and explicitly dismissed. Message dialogs appear at a consistent location on the screen.


A screenshot that illustrates a standard dialog control


Error messages that apply to the overall app context use message dialogs. These are different than error messages that can be conveyed inline. An appropriate example is a message dialog that shows a connectivity error; this critically affects the value that the user can get from the app:

Message dialog example


Here's an example of a message dialog from the Windows device consent broker asking for consent to use location services:

Message dialog example

Dos and don'ts

  • Use message dialogs to convey urgent information that the user must see and acknowledge before continuing. An example is, "Your trial period for advanced features has expired."

  • Use message dialogs to present blocking questions that require the user's input. A blocking question is a question where the application cannot make a choice on the user's behalf, and cannot continue to fulfill it's value proposition to the user. A blocking question should present clear choices to the user. It is not a question that can be ignored or postponed.

  • Use message dialogs to ask for explicit action from the user or to deliver a message that is important for the user to acknowledge. Examples of usages of dialogs are the following:

    • The user is about to permanently alter a valuable asset
    • The user is about to delete a valuable asset
    • The security of the user's system could be compromised
  • Use custom dialogs when the app or the system must invest a significant amount of time in the ensuing actions such that an accidental dismiss would be detrimental to the user's confidence.

  • All dialogs should clearly identify the user's objective in the first line of the dialog's text (with or without a title).

  • Don't use message dialogs when the app needs to confirm the user's intention for an action that the user has taken. Instead, a flyout is the appropriate surface. See Guidelines for flyouts.

  • Don't use message dialogs for errors that are contextual to a specific place on the page, such as validation errors (in password fields, for example), use the app's canvas itself to show inline errors. See Choosing the right UI surfaces: Errors.

Additional usage guidance

All message dialogs should clearly identify the user's objective in the first line of the dialog's text. The following guidelines explain how to use the "title" and "content" fields of the message dialog to convey information effectively.

  • Title (main instruction, optional)

    • Use a short title to explain what people need to do with the dialog. Long titles do not wrap and are truncated.
    • If you're using the dialog to deliver a simple message, error or question, you can optionally omit the title. Rely on the content text to deliver that core information.
    • Make sure the title relates directly to the button choices.
  • Content (descriptive text)

    • Present the message, error, or blocking question as simply as possible without extraneous information.
    • When a title is used, use the content area to provide more detail or define terminology. Don't repeat the title with slightly different wording.
  • Buttons

    • Use buttons with text that identifies specific responses to the main instruction or content. An example is, "Do you want to allow AppName to access your location?", followed by "Allow" and "Block" buttons. Specific responses can be understood more quickly, resulting in efficient decision making.

    • Avoid using generic patterns such as "OK/Cancel".

    • Specify the default button, which should be the action you most want the user to take. In the above example, "Allow" is the default choice.

      • If not specified, the default is the leftmost button.
      • Put the safest, most conservative choice on the rightmost position. In the above example, "Block" is the rightmost choice as it is more conservative.
  • Color

    • Message dialog backgrounds are always white. The primary colors of the app that owns the dialog are used for controls.

For designers

Message dialog sample

Guidelines for context menus

Guidelines for flyouts

Guidelines for clipboard commands

Laying out your UI

For developers (XAML)

MessageDialog class