Dialog modal popup - Web accessibility testing checklist

How to test a dialog modal popup

Gherkin Condensed

Given that I am on a screen with a dialog modal popup

1 Keyboard

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
Then when I use the arrow keys I SEE content in the dialog is browsed in logical order, content behind the dialog remains inert
Then when I use the tab key I SEE focus moves to interactive controls in the dialog, content behind the dialog remains inert
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 dialog
- I HEAR When closed, focus returns to the launch button
- I HEAR When open, content behind the dialog remains inert
Then when I use the arrow keys I HEAR content in the dialog is browsed in logical order, content behind the dialog remains inert
Then when I use the tab key I HEAR focus moves to interactive controls in the dialog, content behind the dialog remains inert
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 screenreader 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 dialog
- I HEAR When closed, focus returns to the launch button
- I HEAR When open, content behind the dialog remains inert
Then when I doubletap with the button in focus I HEAR the dialog opens
Then when I swipe within the dialog I HEAR focus stays trapped in the 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	The dialog opens
Arrow keys	Content within the dialog is browsed in meaningful order
Tab	Focus visibly moves to interactive controls in the dialog, starting with the first control (typically close button)
Escape	The dialog closes and returns focus to the button that launched it
Space	Any focused buttons are activated
Enter	Any focused buttons or links are activated

2 Mobile screenreader gestures

When I use	I hear
Swipe	Focus moves within the dialog, content behind the dialog remains inert
Doubletap	This typically activates most elements

3 Screenreader output

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

Video examples

iOS Voiceover

Android Talkback

Windows Jaws Chrome

MacOS Voiceover Safari

Variations

(Spoiler alert: These all have the same rules.)

Required attributes

The Popover API cannot be used to launch a dialog modal. The Popover element will not have the same semantics or built in features of a JS launched using modal.showModal();

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
- This is a helpful pattern because not every modal has a dismiss button (ex: Alert options for being signed out if user is inactive)
Upon closing, focus must return to the button that launched the dialog

Screenreader differences

NVDA
- By default, NVDA may read the entire modal upon launch. This is expected behavior.
iOS Voiceover
- Voiceover will place focus on the first focusable control, no matter what JS targets for focus

Code examples

<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>

Web Dialog modal popup