uwc-dialog components inform users about a task and can contain critical information, require decisions, or involve multiple tasks.

A dialog is a type of modal window that provides critical information or asks for a decision. A modal window appears on top of the main content – which is disabled, often behind a scrim – and moves the system into a special mode requiring the user to interact with the modal window.

Dialogs disable all app functionality when they appear, and remain on screen until confirmed, dismissed, or a required action has been taken. Dialogs are purposefully interruptive, potentially causing the user to forget what they were doing, so they should be used sparingly. Interruptions only help when they are relevant or helpful to the current task.

Use modal dialogs for important warnings, or to prevent or correct critical errors. Whenever there is a chance that a user's work may be lost or that an action may have destructive, irreversible consequences, interrupt the user to avoid a disaster.

Dialogs are also useful to break complex workflows into smaller or simpler steps that are easier to complete. Wizard dialogs are common example of this dialog usage. Keep in mind that breaking a task into more smaller steps may extend the time it takes to complete the task, so provide a progress indicator to help the user have a sense of how much remains and reduce the chance of abandonment.

Another effective use of dialogs is to collect information that is likely to reduce the user's work or effort significantly, a form of progressive disclosure. While this information may not be critical, using a dialog to collect it at a relevant point in the workflow can streamline the data capture process and focus the user on completing the task.

Things to avoid:

  • Don't use dialogs to collect information that is not critical to completion of the task at hand – Such dialogs can be perceived by users as annoying as they get in the way of what the user is trying to do and can lead to abandonment.
  • Avoid dialogs that interrupt high-stake processes such as checkout flows – While you can use a dialog to focus a user on completing a high-stake process, a dialog that interrupts an important flow can distract the user from completing the flow and even erode the user's confidence.
  • Don't require the user to make a decision in a dialog when that decision is based on information not immediately available in the dialog, especially if the decision is complex or requires additional research.

The following image shows four tabs.

  1. Container
  2. Title
  3. Close button (optional)
  4. Content – Specific to dialog instance
  5. Action buttons (optional)
  6. Scrim

The optional close button appears in the top right corner of a dialog. Click the close button to close the dialog.

Action buttons are optional. When configured, they appear at the bottom of the dialog. Clicking an action button initiates a related action and closes the dialog.

Scrims are temporary treatments that can be applied to surfaces for the purpose of making content on a surface less prominent. They help direct user attention to other parts of the screen, away from the surface receiving a scrim. Dialogs appear on top of a scrim placed over the entire page and which prevents user interaction with the main content.

Action buttons can be stacked. The order of stacked action buttons from top to bottom is the same as unstacked action buttons from right to left.

Closing a dialog hides it and returns focus to the main content. A dialog can be closed by any of the following actions.

  • Clicking the Close button, if available.
  • Clicking an action button, if available.
  • Clicking outside the dialog, on the scrim.

Clicking an action button initiates an associated custom action, in addition to closing the dialog.

Our components have been designed to comply with the WCAG 2.2 AA accessibility guidelines. For more information about how this design system complies with color-related accessibility guidelines, see Foundations > Colors > Accessibility.