What component has
Keyboard support
Key | Function |
---|---|
Tab | Moves focus to the next focusable element. |
Shift + Tab | Moves focus to the previous focusable element. |
Esc | Closes the modal window. |
See more about the focus behavior in the modal window in the Keyboard control guide.
Closing modal window
You can close the modal window by clicking on the following controls:
Close
icon;- CTA or "Cancel" button;
ESC
key;- "Back" in the browser (nothing changes on the parent page);
- outside the container area.
TIP
When the modal window is closed, the focus should always return to the trigger.
Roles & attributes
The list below describes roles and attributes that component already has.
Role | Attribute | Element | Usage |
---|---|---|---|
dialog | div | Identifies the element that serves as the dialog container. | |
aria-labelledby="IDREF" | Gives the dialog an accessible name by referring to the element that provides the dialog title. | ||
aria-modal="true" | div | Tells assistive technologies that the windows underneath the current dialog are not available for interaction (inert). |
Considerations for designers & developers
Attributes
The list below will help you to keep in mind the necessary attributes to make our components fully accessible in the particular cases in your interfaces.
Attribute | Element | Usage |
---|---|---|
aria-describedby="IDREF" | div | Gives the dialog an accessible description by referring to the dialog content that describes the primary message or purpose of the dialog. |
Headings
By default, Modal.Title
in our Modal component is marked as h2
. Since there is no strict WCAG recommendation on this, we've made this decision for the following reason: Modal windows are usually part of the page and don't have a separate URL, so to keep consistency within the page, it's recommended to have only one h1
tag on the page. Having more than one h1
tag per page can confuse users of assistive technology.
However, if your modal window has a separate URL, you can mark Modal.Title
as h1
.
Resources
W3 modal dialog example has detailed information about the modal window accessible behavior.
Other recommendations
See more accessibility recommendations in the common Accessibility guide.
Automated screen reader testing
Intergalactic v15.29.0, React v18.2.0, Playwright v1.25.1, Guidepup v0.13.1, MacOS Monterey 12.
Running screen reader against this file.
1. Screen reader goes into the active element.
2. Screen reader says "Open modal button".
3. Screen reader triggers element default action.
4. Screen reader says "Do you want to save your changes? web dialog with 5 items Close button".
5. Screen reader goes to the next element.
6. Screen reader says "heading level 2 Do you want to save your changes?".
7. Screen reader goes to the next element.
8. Screen reader says "Your changes will be lost if you don't save them.".
9. Screen reader goes to the next element.
10. Screen reader says "Save changes button".
11. Screen reader triggers element default action.
12. Screen reader triggers element default action.
1. Screen reader goes into the active element.
2. Screen reader says "Open modal button".
3. Screen reader triggers element default action.
4. Screen reader says "Do you want to save your changes? web dialog with 5 items Close button".
5. Screen reader goes to the next element.
6. Screen reader says "heading level 2 Do you want to save your changes?".
7. Screen reader goes to the next element.
8. Screen reader says "Your changes will be lost if you don't save them.".
9. Screen reader goes to the next element.
10. Screen reader says "Save changes button".
11. Screen reader triggers element default action.
12. Screen reader triggers element default action.