Morningstar Design System

Dialogs

Variations Design Guidelines Code Reference Accessibility

Dialogs

  • HTML/CSS Available
  • Web Component Beta
  • Last Updated

    2.18.0

Dialogs elicit a response or reveal critical information without losing the context of the underlying page.

Variations Design Guidelines Code Reference Accessibility

Variations

Default

Use to communicate critical information.

Example
Default
Default
Cancel
HTML Web Component 
<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>
<mds-dialog text="You have uploaded an incorrect file type, please only upload .xls files.">
    <mds-button slot="mds-dialog-right-actions" variation="secondary"> Cancel </mds-button>
</mds-dialog>
  • 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
With Primary Action
Cancel Yes, Proceed
HTML Web Component 
<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">
                Yes, Proceed
            </button>
        </div>
    </div>
</div>
<mds-dialog text="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 slot="mds-dialog-right-actions">
        <mds-button variation="secondary"> Cancel </mds-button>
        <mds-button variation="primary"> Yes, Proceed </mds-button>
    </div>
</mds-dialog>
  • 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
With Third Action
Don’t Save
Cancel Save
HTML Web Component 
<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>
<mds-dialog text="Your Workbook contains unsaved data, do you want to save your changes?">
    <mds-button slot="mds-dialog-left-actions" variation="secondary"> Don’t Save </mds-button>
    <div slot="mds-dialog-right-actions">
        <mds-button variation="secondary"> Cancel </mds-button>
        <mds-button variation="primary"> Save </mds-button>
    </div>
</mds-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 modifier classes or props to make the dialog wider.

350px Wide (Default)
500px Wide
350px Wide (Default)
Cancel Yes, Proceed
500px Wide
Cancel Yes, Proceed
HTML Web Component 
<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">
                Yes, Proceed
            </button>
        </div>
    </div>
</div>
<mds-dialog text="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 slot="mds-dialog-right-actions">
        <mds-button variation="secondary"> Cancel </mds-button>
        <mds-button variation="primary"> Yes, Proceed </mds-button>
    </div>
</mds-dialog>

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
<!-- HTML -->
<div class="mds-dialog [my-custom-dialog-width]" role="dialog">
    ...
</div>
<!-- Web Component -->
<mds-dialog class="[my-custom-dialog-width]">
    ...
</mds-dialog>

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.
Dialog With Forms
Dialog With Forms
Workbook Name
Save Column Set
Cancel Save
Don’t Save
HTML Web Component 
<div role="dialog" class="mds-dialog ">
    <div class="mds-dialog__message"> Your Workbook contains unsaved data, do you want to save your changes? </div>
    <form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
        <div class="mds-form__field-group">
            <label class="mds-form__label" for="workbook-name">
                Workbook Name
            </label>
            <input class="mds-form__input" type="text" id="workbook-name">
        </div>
        <div class="mds-form__field-group">
            <label class="mds-form__checkbox" for="dialog-checkbox">
                <input id="dialog-checkbox" type="checkbox" class="mds-form__checkbox-input" checked />
                <span class="mds-form__checkbox-visible-wrap">
                    <span class="mds-form__checkbox-visual">
                        <svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
                            <use xlink:href="/icons/mds.svg#check--s">
                            </use>
                        </svg>
                        <svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
                            <use xlink:href="/icons/mds.svg#minus--s">
                            </use>
                        </svg>
                    </span>
                    <span class="mds-form__checkbox-text">
                        Save Column Set
                    </span>
                </span>
            </label>
        </div>
    </form>
    <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>
<mds-dialog id="my-dialog" text="Your Workbook contains unsaved data, do you want to save your changes?" action-required>
    <div slot="mds-dialog-supplemental-content">
        <form class="mds-form mds-form--medium-layout">
            <div class="mds-form__field-group">
                <mds-label> Workbook Name </mds-label>
                <mds-input></mds-input>
            </div>
            <div class="mds-form__field-group">
                <mds-checkbox checked> Save Column Set </mds-checkbox>
            </div>
        </form>
    </div>
    <div slot="mds-dialog-right-actions">
        <mds-button variation="secondary"> Cancel </mds-button>
        <mds-button variation="primary"> Save </mds-button>
    </div>
    <mds-button slot="mds-dialog-left-actions" variation="secondary"> Don’t Save </mds-button>
</mds-dialog>

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.
  • 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.

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.

Web Component

Props

When setting props as attributes on a custom HTML element, use kebab-case instead of camelCase.

Prop
Type
Validation
Default
Description

actionRequired

Boolean

—

false

If true, requires a user to choose one of the actions in the dialog, cannot be dismissed using the escape key or by clicking the overlay.

additionalClass

String

—

—

A space-separated list of class names that will be appended to the default mds-dialog class.

text

String

Required

—

The text for the dialog. Can also be passed via the default slot.

width

String

One of: 350px, 500px

350px

Alters the width of the dialog.

Slots

Default Slot

Pass text in between the <mds-dialog></mds-dialog> tags to set the dialog’s text content. This can be overridden with the text prop.

Named Slots

Slot Name
Description

mds-left-actions

Displays actions, usually Buttons, on the left side of the dialog.

mds-right-actions

Displays actions, usually Buttons, on the right side of the dialog.

mds-dialog-supplemental-content

Displays supplement content below the dialog’s message, such as an Input.

Methods

Method Name
Description

open()

Opens the dialog.

Events

Event Name
Description

mds-dialog-dismissed

Triggers when the dialog is dismissed.

mds-dialog-activated

Triggers when the dialog is opened.

Usage Examples

Setting text, id, and actionRequired via props. Using named slots for mds-dialog-right-actions, mds-dialog-left-actions, and mds-dialog-supplemental-content:

<mds-dialog text="Do you want to save your list?" action-required>
    <div slot="mds-dialog-supplemental-content">
        <form class="mds-form mds-form--medium-layout">
            <mds-field-group>
                <mds-label for="file-name-input"> File Name </mds-label>
                <mds-input id="file-name-input"></mds-input>
            </mds-field-group>
        </form>
    </div>
    <div slot="mds-dialog-right-actions">
        <mds-button variation="secondary"> Cancel </mds-button>
        <mds-button variation="primary"> Save </mds-button>
    </div>
    <mds-button slot="mds-dialog-left-actions" variation="secondary"> Don’t Save </mds-button>
</mds-dialog>

Implementation

  • Include role=”dialog” in .mds-dialog element attributes.
  • Always give the .mds-dialog__message element a unique id and set it as the .mds-dialog element’s aria-describedby attribute. For example:
<div role="dialog" class="mds-dialog " aria-describedby="mds-dialog-example--0001">
    <div class="mds-dialog__message" id="mds-dialog-example--0001"> You have uploaded an incorrect file type, please only upload .xls files. </div>
    ...
</div>

Best Practices

  • Include at least one focusable element in the dialog, usually be a button.
  • Lock focus within the dialog when it’s open.
  • 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.
  • 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.