Modal Dialog

How to test a modal dialog

Gherkin Condensed WCAG

Given that I am on a page with a modal dialog

1 Keyboard for mobile & desktop

WHEN I use the tab key to move focus to the launch button and use spacebar and/or enter key to activate the button I SEE the dialog opens and is in focus
Then when I use the arrow keys I SEE content in the dialog is browsed in logical order and does not leave the dialog
Then when I use the tab key I SEE focus moves to interactive controls in the modal dialog
Then when I use the escape key I SEE focus returns to the launch button
Or when I use the tab key to move focus to the dismiss/close button AND THEN use the spacebar or enter key to activate the dismiss/close button I SEE focus returns to the launch button

2 Desktop screenreader

WHEN I use a desktop screenreader (NVDA, JAWS, VoiceOver) AND I use the tab key to move focus to the launch button and use spacebar and/or enter key to activate the button
- I HEAR The dialog describes its purpose or title on launch
- I HEAR It identifies itself as a modal or dialog
- I HEAR When closed, focus returns to the launch button
- I HEAR When open, content behind the modal remains inert
Then when I use the arrow keys I HEAR content in the dialog is browsed in logical order and does not leave the dialog
Then when I use the tab key I HEAR focus moves to interactive controls in the modal dialog
Then when I use the escape key I HEAR focus returns to the launch button
Or when I use the tab key to move focus to the dismiss/close button AND THEN use the spacebar or enter key to activate the dismiss/close button I HEAR focus returns to the launch button

3 Mobile screenreader

WHEN I use a mobile screenreader (Talkback, VoiceOver) AND I swipe to focus to the launch button
- I HEAR The dialog describes its purpose or title on launch
- I HEAR It identifies itself as a modal or dialog
- I HEAR When closed, focus returns to the launch button
- I HEAR When open, content behind the modal remains inert
Then when I doubletap with the button in focus I HEAR the dialog opens
Then when I swipe within the modal dialog I HEAR focus stays trapped in the modal dialog
Then when I swipe to move focus to the dismiss/close button AND THEN double tap on the close button I HEAR focus returns to the launch button

1 Keyboard & screen reader actions

When I use	I see/hear
Launch button	Focus visibly moves to the open dialog itself
Arrow keys	Content within the dialog is browsed in logical order
Tab	Focus visibly moves to interactive controls in the dialog, starting with the first interactive control (typically close button)
Escape	The dialog closes and returns focus to the button that launched it
Space	Any buttons are activated
Enter	Any buttons or links are activated

2 Mobile screenreader gestures

When I use	I hear
Swipe	Focus moves within the dialog and doesn't enter the rest of the page.
Doubletap	This typically activates most elements.

3 Screenreader output for all devices

Reads	I hear
Name	The dialog describes its purpose or title on launch
Role	It identifies itself as a modal or dialog
Group	When closed, focus returns to the launch button
State	When open, content behind the modal remains inert

A modal dialog must meet these WCAG principles.

1Perceivable

Is easy to identify as a modal dialog on top of a page (and not a new page)

2Operable

Is keyboard operable
The close button click/tap target area is no smaller than 44x44px
The focus indication has a 3:1 minimum contrast ratio against adjacent elements
The focus indication has a minimum area equal to the width of the element and 2px in height

3Understandable

Its purpose and title is clear in the context of the whole page

4Robust

Conveys the correct semantic role
Meets criteria across platforms, devices and viewports

Video examples

iOS Voiceover

Android Talkback

Windows Jaws Chrome

Windows NVDA Chrome

MacOS Voiceover Safari

Required attributes

Launch button

Should be a button, not a link
Upon closing, focus must return to the button that launched the dialog
Do not usearia-haspopup. This attribute has very low and support and unpredictable output across screen readers.

Name

The modal window has a logical descriptive name from either:
- aria-label="Modal title" or
- aria-labelledby="heading-id" pointing to an <h2> as a title

Role

Use role="dialog" so the screen reader can identify this as a dialog or modal

Group

Upon closing, focus must return to the button that launched the dialog

State

Use aria-modal="true" to indicate content beneath the modal is inert and that the screen reader must not browse outside the dialog.

Focus

Use tabindex="-1" to make the modal itself targetable for focus
Upon closing, focus must return to the button that launched the dialog

Documentation

Browser Support

Screenreader differences

NVDA
- By default, NVDA may read the entire modal upon launch. This is expected behavior.

Code examples

Use semantic HTML where possible

Browser support for <dialog> is still incomplete.

Some browsers require additional scripting. This simple example works in Chrome, but may not work correctly in all browsers such as Safari and Firefox.

<button id="showModal">
  Things you should know
</button>

<dialog role="dialog"
        id="modal"
        tabindex="-1"
        aria-modal="true"
        aria-labelledby="dialog-title">
  <button type="button"
          id="closeModal"
          class="close">
    <span class="hidden">Close</span>
  </button>
  <div class="dialog-content">
    <h2 id="dialog-title" class="h-bravo">
      Things you should know
    </h2>
    <h3>Keyboard</h3>
    <ul>
      <li>Focus must not enter the rest of the page.</li>
      <li>The escape key must close the modal.</li>
    </ul>
    <h3>Screenreader</h3>
    <ul>
      <li>The modal's title is announced on launch.</li>
      <li>The screen reader cannot read content behind the dialog.</li>
    </ul>
    <button type="submit">
      Continue
    </button>
  </section>
</dialog>