Modal dialogs

Understand how to create and test for accessible modal dialogs.

On this page

• What is a modal dialog?

• How to create a modal dialog

• When to use modal dialogs

• When not to use modal dialogs

• Accessibility considerations

• Usability best practices

Meeting the Web Accessibility Standard

When a modal dialog’s accessible name can be programmatically determined and means the same thing as its visible label, this meets WCAG 2 Success Criterion (SC) 1.3.1 Info and Relationships.

When a modal dialog’s role and accessible name can be programmatically determined, this meets WCAG 2 SC 4.1.2 Name, Role, Value.

When a modal dialog can be launched, interacted with, and closed using a keyboard, this meets WCAG 2 SC 2.1.1 Keyboard.

When a modal dialog traps keyboard focus within it until the dialog is closed, this meets WCAG 2 SC 2.4.3 Focus Order.

What is a modal dialog?

A modal dialog is a pop-up window that appears on a web page or application. People must interact with this window before they can return to the main page.

Because modal dialogs block the main content until people complete the action or close the modal, it’s important to make sure they are fully accessible.

How to create a modal dialog

Accessible modal dialogs can be made a few ways. No matter how it’s made, test it thoroughly to make sure it meets requirements.

Using <dialog> with showModal()

HTML now has a widely supported <dialog> element that can be used. Using its built-in showModal() method, the dialog is launched such that:

• it appears on top of the current window and any other dialogs that might be open

• the underlying document is inert and cannot be interacted with

• keyboard focus is automatically moved to the dialog or a focusable element inside it

• keyboard focus is trapped within the dialog, as expected.

For instructions and examples, refer to:

• <dialog>: The Dialog element — MDN Web Docs

• HTMLDialogElement: showModal() method — MDN Web Docs

• The dialog element — HTML Living Standard.

Using ARIA role="dialog" and custom JavaScript

If you need to support older browsers like Internet Explorer 11, you’ll need to create your own modal dialog using the ARIA dialog role and custom JavaScript. For more, see Modal Dialog Example — ARIA Authoring Practices Guide — W3C.

Or consider using this prepared script: a11y-dialog — KittyGiraudel — GitHub.

When to use modal dialogs

As a rule, use modal dialogs sparingly. They can create an unnecessary cognitive burden by interrupting workflow, distracting users, or being accidently dismissed before the information is read.

Use a modal dialog only to direct users’ attention to critical information that requires immediate attention, or when other design options do not provide a good user experience.

If you’re thinking of using a modal dialog, ask why you are using it and if there’s another approach.

The Nielsen Norman Group has guidelines to help you determine if modal dialogs are necessary. Here are the first 2:

1. Use modal dialogs for important warnings, as a way to prevent or correct critical errors. The key words here are ‘critical errors’. Use modal dialogs to warn people when they’re about to do something that cannot be changed or will result in a loss of information. For example, a ‘Save Changes’ modal appears when a person is about to exit the application without saving or submitting their changes.

2. Use modal dialogs to request the user to enter information critical to continuing the current process. Examples include:

• displaying a ‘Login’ dialog when a person tries to perform an action that is restricted to registered users

• presenting a ‘Timeout’ dialog when a logged-in user has been inactive for a set duration.

For more, see Modal & Nonmodal Dialogs: When (& When Not) to Use Them — Nielsen Norman Group.

When not to use modal dialogs

Avoid using modal dialogs when displaying:

• form validation errors — there are other user-friendly ways to present form errors to users

• a lot of information that requires the user to scroll — consider presenting the information on its own page.

Also avoid displaying multiple dialogs on top of each other.

Accessibility considerations

Focus management

Modal dialogs must work for people who rely on a keyboard. For more on enabling and testing keyboard access, see Keyboard accessibility — Knowledge Area: Accessible UX best practices.

When a dialog is opened

Where focus should be placed when the modal dialog opens is context dependent. Often, the most reliable approach is to set focus to the dialog container. However, in some cases it might make more sense to set focus to an interactive element in the dialog.

1. A modal dialog contains a short sentence followed by an ‘OK’ button. Here, the most logical approach is to set focus to the ‘OK’ button.
2. A modal dialog has a lot of content and the ‘OK’ button is placed after the content. Here, setting focus to the ‘OK’ button could force users to navigate back to the top of the dialog to read the content. In this case, set focus to the dialog container itself.

For more information, see Where to Put Focus When Opening a Modal Dialog — Adrian Roselli.

While a modal is open

Trap focus within the modal dialog until the user closes it. To test this, once the dialog is open, press the Tab key repeatedly. Focus should remain within the dialog and not move to any element in the underlying page.

When a modal is dismissed or closed

After the modal dialog is closed, set keyboard focus to the element that triggered the dialog to open. This is typically a button.

Keep the underlying page inert

The underlying page from which the dialog was launched is supposed to be inert or non-interactive for everyone while the dialog is open. However, it’s common for screen reader users to still have access to and be able to interact with elements in the underlying page.

If the modal dialog uses the HTML <dialog> element and is opened using the showModal() method, the underlying page will automatically be inert for everyone, including screen reader users.

With custom modal dialogs, set aria-hidden="true" on elements outside the modal dialog, which hides those elements from screen readers. For more on aria-hidden, see State for hiding content from AT — Knowledge Area: Fundamental concepts in web accessibility.

Test this with a screen reader by using its navigation quick keys or gestures to try moving to next or previous headings, or to other parts of the underlying page.

For more on hiding the underlying page from screen readers, see the Notes on aria-modal and aria-hidden from the Modal Dialog Example — ARIA Authoring Practices Guide — W3C.

Dialog role and accessible name

The modal dialog container must have a role of dialog. If the dialog uses the <dialog> element, this happens by default. Otherwise, add role="dialog" to the dialog’s container. For more on this role, see:

• ARIA: dialog role — MDN Web Docs

• dialog role — Accessible Rich Internet Applications (WAI-ARIA) — W3C.

Identifying the element’s role helps screen reader users understand the function or behaviour of the component they are interacting with. For more, see Roles — Knowledge Area: Fundamental concepts in web accessibility.

The modal dialog must also have an accessible name that identifies the purpose of the dialog to screen readers. Use either aria-labelledby or the aria-label attribute to provide an accessible name. For more, see Using aria-label and aria-labelledby — Knowledge Area: Fundamental concepts in web accessibility.

If possible, give the modal dialog a heading at the appropriate level based on its position in the heading hierarchy. If the dialog is triggered from an element whose preceding heading is an <h2>, use an <h3> element for the dialog. Refer to the heading’s id using aria-labelledby attribute on the dialog container element.

How users can close the modal

The user must be able to close the modal dialog:

• using a ‘Close’, ‘OK’ or a ‘Cancel’ button

• using the Esc key.

Usability best practices

Consider the following to enhance the overall user experience and effectiveness of modal dialogs.

• Use short messages that are easy to read and understand.

• Ensure that the message contains the necessary information, and that it can stand alone without requiring people to reference the main content.

• Keep the interaction quick and easy to reduce the possibility of errors.

• Clearly label actionable controls.