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 to use with each modal type:
* Required property
** Required in certain cases
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.
modal | dialog
Usage in HTML
Edit the code below to see changes reflected in the example above.
Example code for functionality.
Usage in Elm
Code generated from HTML.
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.
|Activates the close button, secondary button, or primary button.
|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.