Modal & Dialog

Modals display content over the page. There are two types: multi-functional modals and dialogs. Each has different styles and uses. Both are composed of a wm-modal-header, a wm-modal-footer, and variable content to display between them.

The modal component has no control over the content passed to it. Check the Notes tab to understand the implications (you might in particular experience unexpected behavior with scrolling).

For accessibility reasons, the component should always be rendered on the page, whether it is visible or not. The component itself should control whether the modal is displayed or not; you should NOT conditionally render the component. See the Notes sections for more information.

Properties

Examples

Events

Accessibility

Notes

Properties to use with each modal type:

open: Required

id: Optional

elementToFocus: Optional

heading: Required

subheading: Optional

primaryText: Required

secondaryText: Optional

infoText: Optional

primaryActionDisabled: Optional

deleteStyle: Optional

open: Required

id: Optional

elementToFocus: Optional

modalType: Required

heading: Required

primaryText: Required

secondaryText: Optional

deleteStyle: Optional

* Required property

** Required in certain cases

Properties of `wm-modal`

open *

boolean

Required. The state of the modal.

element-to-focus

"primary" | "secondary" | [id]

This determines which element to focus when the modal opens. If an element in the modal body should be focused, set this property to the id of the element.

If a button in the modal footer should receive focus, set this property to "secondary" or "primary". When this is the case, the modal must be given an id, and the modal body should have an ID set to "content-[modal-id]". See the first example on the Examples tab.

If no value is passed, the modal will automatically focus the close button in the top right corner.

id **

string

The id of the modal. This attribute is required (for accessibility purposes) if a button in the footer receives focus when the modal opens.

Properties of `wm-modal-header`

heading *

string

Required. The heading text to display.

subheading

string

Descriptive text to display below the heading. Should not be used with type dialog.

Properties of `wm-modal-footer`

primary-text *

string

Text to display in the primary action button.

secondary-text

string

Text to display in the secondary action button.

info-text

string

Text to display in the lower left corner of the footer to provide additional feedback or information to the user. Should not be used with type dialog.

primary-action-disabled

boolean

Disables the primary action button in the footer.

delete-style

boolean

Renders the primary action button with the permanently delete button style.

Deprecated properties

is-open *

boolean

Previously, the state of the modal. Deprecated in favor of open.

Usage in HTML

Edit the code below to see changes reflected in the example above.

<wm-button id="sb" button-type="secondary" onClick="openModal('mydialog')">Open Dialog</wm-button>
<wm-button id="sb2" button-type="primary" onClick="openModal('mymodal')">Open Modal</wm-button>

<wm-modal open="false" modal-type="dialog" id="mydialog" element-to-focus="secondary">
  <wm-modal-header heading="Dialog Example"></wm-modal-header>
    <div id="content-mydialog">
      This is a dialog prompting you to make a decision.
    </div>
  <wm-modal-footer primary-text="Delete" secondary-text="Keep" delete-style="true" ></wm-modal-footer>
</wm-modal>

<wm-modal open="false" element-to-focus="name-input" id="mymodal">
  <wm-modal-header heading="Multi-Functional Modal Example" subheading="User input solicited below"></wm-modal-header>
    <div>
      <div>
        <label for="name-input">Name</label>
        <input id="name-input" onInput="checkInput()"/>
      </div>
      <div>
        <label for="color-input">Favorite Color</label>
        <input id="color-input" />
      </div>
    </div>
  <wm-modal-footer primary-text="Save" primary-action-disabled="true" secondary-text="Cancel" info-text="Name is required."></wm-modal-footer>
</wm-modal>

Javascript Sample

Example code for functionality.

const modals = document.querySelectorAll("wm-modal");

function openModal(id) {
  const modal = document.getElementById(id);
  modal.open = true;
}

function closeModal(ev) {
  const modal = ev.target;
  modal.open = false;
};

modals.forEach((modal) => {
  modal.addEventListener("wmModalCloseTriggered", (ev) => closeModal(ev));
  modal.addEventListener("wmModalPrimaryTriggered", (ev) => closeModal(ev));
  modal.addEventListener("wmModalSecondaryTriggered", (ev) => closeModal(ev));
});

function checkInput() {
  const modal = document.getElementById("mymodal");
  const input = document.getElementById("name-input");
  const footer = modal.querySelector("wm-modal-footer");
  if (input.value) {
    footer.primaryActionDisabled = "false";
  } else {
    footer.primaryActionDisabled = "true";
  }
}

Usage in Elm

Code generated from HTML.

wmModalCloseTriggered

Emitted when the close button has been clicked. Replaces the deprecated wmCloseTriggered.

wmModalPrimaryTriggered

Emitted when the primary button has been clicked. Replaces the deprecated wmPrimaryTriggered.

wmModalSecondaryTriggered

Emitted when the secondary button has been clicked. Replaces the deprecated wmSecondaryTriggered.

Screen Reader

The multi-functional modal and dialog are both announced as dialogs by the screen reader. Sometimes a button in the footer receives focus when the modal opens. In these cases, the attribute "aria-describedby" is set on the modal, pointing to the id of the modal content. This ensures that the screen reader exposes the content of the modal to the user.

Keyboard Support

Key	Function
`Enter` `Space`	Activates the close button, secondary button, or primary button.
`Tab`	Moves focus to the next focusable element. If the user reaches the end of the modal, focus will move to the first focusable element in the modal (the close button).
`Shift + Tab`	Moves focus to the previous focusable element. If the user reaches the top of the modal, focus will move to the last focusable element in the modal (the primary action button).

The modal component has no control over the content passed to it, which means you need to ensure its content is fully accessible.
Because it cannot control this content but still constrains its height, you will have to set the overflow property of your content to "auto" on the element wrapping your content if you want overflowing content to be scrollable. You may have to reset the scrollTop value to reset the scroll position when the modal is reopened after being scrolled.
The component should be rendered when the DOM loads in order for screen readers to detect the live region. Do NOT conditionally render the component based on whether the modal should show or not; instead, render the component and toggle its "is-open" attribute.
Another issue that could happen if conditionally rendering the component is that page scrolling might break: When the modal opens, the component changes the overflow property of the body element to prevent scrolling. It restores the property to its initial value when it closes. If you conditionally render you may remove the component before it could have a chance to restore the overflow value.

Modal & Dialog

Properties of wm-modal

Properties of wm-modal-header

Properties of wm-modal-footer

Deprecated properties

Usage in HTML

Javascript Sample

Usage in Elm

Screen Reader

Keyboard Support

Properties of `wm-modal`

Properties of `wm-modal-header`

Properties of `wm-modal-footer`