Skip to content

Modal

What component has

Keyboard support

Keyboard support
KeyFunction
TabMoves focus to the next focusable element.
Shift + TabMoves focus to the previous focusable element.
EscCloses 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.

Roles & attributes
RoleAttributeElementUsage
dialogdivIdentifies 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"divTells 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.

Attributes
AttributeElementUsage
aria-describedby="IDREF"divGives 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.

Released under the MIT License.

Released under the MIT License.