missing-dialog-semantics

A modal dialog changes the context of the page: users are asked to focus on the dialog before returning to the rest of the content. Sighted users see this change, because the dialog appears on top of the page. Users of assistive technology learn about it only when the dialog is exposed as a dialog in the accessibility tree. When a modal is built from generic elements, such as a plain <div>, without dialog semantics, screen reader users don't know that they have moved into a different part of the page. They may not realize a dialog has opened, what it is for, or that the content behind it is unavailable.

To give a modal the proper semantics, use a native <dialog> element or add role="dialog" to the modal's container. Both need additional attributes to work correctly:

• A native <dialog> must be opened with showModal() to be modal, and it needs an accessible name, for example aria-labelledby pointing to its heading.
• A custom role="dialog" needs aria-modal="true" and an accessible name.

Pass Patterns

Native <dialog> opened with showModal()

The native element exposes the dialog role, showModal() makes it modal, and aria-labelledby gives it a name.

<dialog id="delete-dialog" aria-labelledby="delete-title">
    <h2 id="delete-title">Delete file?</h2>
    <button>Cancel</button>
    <button>Delete</button>
</dialog>


<script>
    document.getElementById("delete-dialog").showModal();
</script>

Custom modal with role="dialog"

The container has role="dialog", aria-modal="true", and an accessible name from its heading.

<div role="dialog" aria-modal="true" aria-labelledby="delete-title">
    <h2 id="delete-title">Delete file?</h2>
    <button>Cancel</button>
    <button>Delete</button>
</div>

Fail Patterns

Modal built from a plain <div>

The modal looks like a dialog, but it has no dialog role, so assistive technology exposes it as ordinary page content.

<div class="modal">
    <h2>Delete file?</h2>
    <button>Cancel</button>
    <button>Delete</button>
</div>

WCAG techniques

Sufficient techniques

• ARIA4: Using a WAI-ARIA role to expose the role of a user interface component
• G108: Using markup features to expose the name and role, allow user-settable properties to be directly set, and provide notification of changes

Try It Yourself

Using a screen reader

1. Load the page and open a screen reader.
2. Open the modal dialog.
3. Listen to what the screen reader announces.

Expected results: The screen reader announces a dialog and its name, for example “Delete file?, dialog”.

Actual results: The screen reader announces only the content inside the modal, with no indication that a dialog has opened.

Inspecting the browser dev-tools

1. Open the modal dialog.
2. In your browser's dev tools, select the modal's container and open the Accessibility panel.
3. Check the container's role.

Expected results: The role is dialog, and the container has an accessible name.

Actual results: The role is generic, or the container has no dialog role at all.

FAQ

Standards and Regulations

Personas impacted by this issue

• Screen Reader
• Braille

Learn More

• WAI-ARIA Authoring Practices: Dialog (Modal) Pattern

Related Issues

• dialog-has-no-aria-modal
• aria-dialog-name
• modal-background-not-inert
• focus-on-modal-open