Rippleprimary-text *
string
Text to display in the primary action button.
Components / Library Version 5.4.0
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
Properties of wm-modal
open *
boolean
Required. The state of the modal.
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.
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.
modal-type
modal | dialog
Changes the modal's type. Defaults to
modal.
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
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.
Usage in HTML
Edit the code below to see changes reflected in the example above.
Javascript Sample
Example code for functionality.
Usage in Elm
Code generated from HTML.
wmModalCloseTriggered
Emitted when the close button has been clicked.
wmModalPrimaryTriggered
Emitted when the primary button has been clicked.
wmModalSecondaryTriggered
Emitted when the secondary button has been clicked.
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.
- On close, ensure that focus is properly returned to the element that opened Modal. The component handles this. If you run into a special case where this functionality breaks, you can listen to the
wmModalCloseTriggeredevent and return focus in the callback. Please let us know of your use case so we can update the component.
