Morningstar Design System v2.2.0

Variations

Default

Use to communicate critical information.

Example

Default

White Light Dark Black

<div role="dialog" class="mds-dialog ">
    <div class="mds-dialog__message"> You have uploaded an incorrect file type, please only upload .xls files. </div>
    <div class="mds-dialog__action-buttons">
        <div class="mds-dialog__cancel-resolve-buttons-holder">
            <button class="mds-button mds-dialog__cancel-button" type="button"> Cancel </button>
        </div>
    </div>
</div>

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.

Example

With Primary Action

White Light Dark Black

<div role="dialog" class="mds-dialog ">
    <div class="mds-dialog__message"> Turning off logic mode will remove all parentheses and change the connection between all widgets back to &ldquo;and&rdquo;. Are you sure you want to proceed? </div>
    <div class="mds-dialog__action-buttons">
        <div class="mds-dialog__cancel-resolve-buttons-holder">
            <button class="mds-button mds-dialog__cancel-button" type="button"> Cancel </button>
            <button class="mds-button mds-dialog__resolve-button mds-button--primary" type="button"> Continue </button>
        </div>
    </div>
</div>

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

Example

With Third Action

White Light Dark Black

<div role="dialog" class="mds-dialog ">
    <div class="mds-dialog__message"> Your Workbook contains unsaved data, do you want to save your changes? </div>
    <div class="mds-dialog__action-buttons">
        <button class="mds-button mds-dialog__reject-button" type="button"> Don’t Save </button>
        <div class="mds-dialog__cancel-resolve-buttons-holder">
            <button class="mds-button mds-dialog__cancel-button" type="button"> Cancel </button>
            <button class="mds-button mds-dialog__resolve-button mds-button--primary" type="button"> Save </button>
        </div>
    </div>
</div>

Place the primary Button at the bottom right of the dialog.
Place the opposite of the primary action at the bottom left 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).

350px Wide (Default)

500px Wide

White Light Dark Black

<div role="dialog" class="mds-dialog ">
    <div class="mds-dialog__message"> Turning off logic mode will remove all parentheses and change the connection between all widgets back to “and”. Are you sure you want to proceed? </div>
    <div class="mds-dialog__action-buttons">
        <div class="mds-dialog__cancel-resolve-buttons-holder">
            <button class="mds-button mds-dialog__cancel-button" type="button"> Cancel </button>
            <button class="mds-button mds-dialog__resolve-button mds-button--primary" type="button"> Continue </button>
        </div>
    </div>
</div>

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

[.my-custom-dialog-width] {
    max-width: 600px;
}

Product Markup

<div class="mds-dialog [my-custom-dialog-width]" role="dialog"> ... </div>

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

Center dialogs horizontally and vertically in the viewport.

Appropriate centering of a dialog.

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.

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.
The aria-describedby attribute should but used to describe the content of the dialog.
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

Class	Applies to	Outcome
`mds-dialog--active`	`mds-dialog`	Indicates that the dialog is active.
`mds-dialog--width-500px`	`mds-dialog`	Renders a 500px wide dialog.
`mds-dialog--fadeout`	`mds-dialog`	Fades out the `mds-dialog` with animation.

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.