Dialogs

Variations

Default

Use to communicate critical information.

• Dismiss a dialog by:
  • Clicking secondary Button.
  • Pressing the escape key.
  • Clicking outside the dialog.

With Primary Action

Use to communicate critical information that presents the user with a choice.

• Place the primary Button at the bottom right of the dialog.
• Use to communicate critical information that requires confirmation or when a user’s action would result in data loss.
• Requires intentional confirmation or cancellation. This dialog cannot be dismissed by pressing the escape key or by clicking outside of the dialog.

With Third Action

• Place the primary Button at the bottom right of the dialog.

Sizing

Dialogs are available at a single size, which uses $mds-font-size-m (16px) text for the message and medium Buttons.

Widths

Dialogs are available in two predefined widths. The default width is 350px and you can use a modifier class to make the dialog wider (mds-dialog--width-500px).

Customizing Widths

Predefined widths are a starting point. If requirements call for a different dialog width, work with a designer to create custom width styles in your product’s CSS.

Product CSS

Product Markup

Examples

Dialog With Forms

Dialogs will often contain form elements, for example, when allowing a user to name a file they are saving. This example shows how Form markup can be injected in to a dialog. It uses a with primary action dialog, Label, Input, and Checkbox.

MDS Features

• Uses the default markup for the with primary action dialog.
• Uses default Form markup, including wrapping all form elements within a <form> and wrapping all related elements in mds-form__field-group containers. See the grouping elements guidelines in the Forms composition section for more information.
• Uses the mds-form--medium-layout modifier class to apply margin-based spacing to all form elements. See the spacing elements guidelines in the Forms composition section for more information.

Customizations

• Form markup is injected in to the dialog markup to render in the desired location, following a product designer’s design spec.

Guidelines

Use When

• Displaying content critical to a workflow, or when requiring an action or confirmation before proceeding.
• Alerting a user that their action would result in data loss.
• Asking the user to save a state or modification.

Don't Use When

• Displaying non-critical information that doesn’t need to interrupt a workflow. Instead, use a Notification.
• Gathering information or requiring the user to complete a task. Instead, use a Modal.

Visual Language

• When relevant, use medium Form elements within dialogs.
• Use a page overlay (.mds-overlay) to partially block out the underlying page and focus attention on the dialog contents.
• Consider applying a custom z-index value when you compose this component with other layered components, e.g., Modals, Tooltips, Popovers or Notifications to meet your product requirements.

Editorial

• Aim for brief expressions of cause and effect. Try for no more than 2 sentences.
• In a non-judgemental way, tell the user why their action failed, if relevant, and what they can do to resolve their error. Don’t leave them hanging.
• If there’s more than 2 sentences of information to relay, consider using a Modal.
• When stating opposite actions in nearby buttons, try to use the same root verb, i.e., Don’t Save / Cancel / Save.

Accessibility

• Include role=”dialog” in .mds-dialog element attributes.
• Include an aria-describedby attribute with .mds-dialog.
• Always give the .mds-dialog__message element a unique id and set it as the .mds-dialog element’s aria-describedby attribute. For example:

• Include at least one focusable element, this will usually be a button.
• Prevent access to other elements of the page by storing the reference of last focused page element and tabIndex status for all elements. Then, remove the page element’s tab group and focus status.
• Limit tab order to loop only through dialog elements while a dialog is open.
• Restore the underlying page’s tab order when a dialog is closed.
• Restore the focus state for the last focused item before the dialog was opened, which will likely be the trigger that initiated the .mds-dialog.

Code Reference

CSS Class References

JavaScript Considerations

• The dialog is usually integrated into the system / framework code, such as React, Angular, etc., or in-house JavaScript framework. Hence, we encourage teams to implement their own dialog JavaScript. MDS provides interactive dialog examples strictly for documentation and reference.
• The dialog will block all other interactions on the page. Therefore, attach the dialog popup container just before the end of the page closing tag.
• Disable the tab-index on the page beneath the page overlay.
• When the dialog is dismissed, restore the last focused page element, and resume the tab-index for the underlying page contents.
• One approach to capture user operations in a dialog is to use a JavaScript Promise.
  • Look up Resolve, Reject, and Cancel, which are sufficient for mapping the prime, reject and close buttons.
  • Futher references:
    • https://spring.io/understanding/javascript-promises
    • https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise
  • Note IE11 does not support JavaScript Promises. You may need to consider writing your own Promise / Deferred solution in plain JavaScript for asynchronous capturing Resolve, Reject and Cancel user actions.
• Applying the mds-dialog--fadeout class and mds-overlay--fadeout class will animate the dialog.
  • To fade in, apply both classes to the respective DOM nodes at dialog start, wait for a short period (i.e., 10ms), then remove the classes.
  • Once an asynchronous dialog action has been taken by a user, apply the two classes again for the fade out.