Dialog

Reported as: Element has incorrect role

A modal dialog must convey the dialog or alertdialog role, and its launcher the button role.

When the container has no role, or a generic one, screen reader users who are moved into it hear its content as ordinary page content. Nothing says a dialog opened or that it has to be dealt with first. When the launcher has no role or a link role, users don't know it acts on the page.

Use the <dialog> element, or put role="dialog" on a custom container. Use alertdialog for an urgent message that needs a response. Build the launcher from a <button> element, or give a custom one role="button".

Severity: Critical

Reported as: Incorrect root element

A modal dialog's role should sit on the element that contains all of its content, and the launcher's role on the element that takes focus and handles activation.

When the role is on an inner wrapper while the outer element carries the name, aria-modal, and the dialog's controls, or the other way round, no single element is the dialog. Screen reader users hear an unnamed dialog, and can find its close button reported as outside it. On the launcher, a misplaced role announces a button that isn't the element users operate.

Put the dialog's role, accessible name, and aria-modal on one container, and keep any layout wrapper free of them. Put the launcher's role, name, focus, and activation handling on one element.

Reported as: Accessible name

A modal dialog's launcher must have an accessible name that says what the dialog is for.

When the launcher is an icon with no text or alt text, screen readers announce only "button", and users can't tell what it opens until they're inside the dialog.

Name the launcher with visible text, an image's alt text, or aria-label, and keep the name short and specific to the dialog's task.

Severity: Critical

Reported as: Missing contextual labeling

A modal dialog must have an accessible name that says what it's for.

When the dialog has no name, screen reader users are moved into it and told only that they're in a dialog. On a page that can open several, they can't tell which one appeared, and they have to read its content to find out what it's asking.

Name the dialog from its visible title with aria-labelledby. When it has no title, point aria-labelledby at the launcher's text, or use aria-label when there's no visible text to point at. Name it for its task, such as "Delete this item?", rather than "Dialog".

Severity: Moderate

Reported as: Missing aria-modal attribute

A custom modal dialog should carry aria-modal="true" on the element with the dialog role.

When the attribute is missing, nothing tells assistive technology that the page outside is meant to be unavailable. Tab may stay inside, but screen reader users reading by line or by heading aren't bound by focus traps, and nothing suggests they should stay.

Set aria-modal="true" on the dialog element itself, not on a wrapper. When the closed dialog stays rendered, remove the attribute on close. The attribute declares modality and doesn't create it, so still make the page outside inert.

Severity: Minor

Reported as: Component does not support disabled state

A modal dialog must not declare a disabled state, which the dialog and alertdialog roles don't support.

When disabled or aria-disabled is set on the dialog, screen reader users can hear it described as unavailable while every control inside it still works, or hear nothing at all of what the design meant.

Remove the attribute from the dialog, and disable each control inside it that's unavailable.

Severity: Serious

Reported as: Element type does not support disabled state

An element in a dialog must carry disabled or aria-disabled only when its role supports a disabled state.

When the state sits on an element whose role has none, such as a wrapper, a list item or a heading, assistive technology may drop it or report it on something users can't operate, while the control that really is unavailable is still reported as available.

Remove the attribute from that element, and set the disabled state on the control itself, using an element or role that supports it, such as a native <button>.

Severity: Serious

Reported as: Conflicting disabled values

A modal dialog's launcher must declare its disabled state one way only: the disabled attribute on a native <button>, or aria-disabled on a custom launcher.

When a native launcher carries aria-disabled instead of disabled, it still opens the dialog while assistive technology reports it as unavailable. When both attributes are set and disagree, screen reader users are told the wrong thing about whether the dialog can be opened.

Use disabled alone on a native launcher and aria-disabled alone on a custom one, removing it or setting it to false when the launcher is enabled again.

Severity: Serious

Reported as: Element does not support the disabled attribute

A custom launcher built from an element that doesn't support the disabled attribute must convey its disabled state with aria-disabled.

When disabled is set on a <div> or <span> launcher, browsers ignore it. The launcher looks unavailable, but assistive technology reports it as enabled, and keyboard and screen reader users can still open a dialog whose task isn't meant to be available.

Set aria-disabled="true" instead, and block activation in the launcher's event handlers while it's set.

Severity: Serious

Reported as: Modal is not available to assistive technology

An open modal dialog must be in the accessibility tree, with the dialog or alertdialog role.

When the dialog keeps aria-hidden="true" in its open state, or sits inside a hidden ancestor, screen reader users hear an unchanged page that has stopped responding, with no sign a dialog opened. When it's present without a role, its content reads as ordinary page content, and nothing says it has to be dealt with first.

Give the container the dialog role, or alertdialog for an urgent message. When it opens, clear aria-hidden from it and its ancestors, and remove any hidden attribute or display: none.

Severity: Critical

Reported as: Hidden modal available to assistive technology

A closed modal dialog must be out of the accessibility tree.

When the dialog is closed by moving it off screen or fading it to transparent, its heading, text, and buttons stay in the page for screen reader users, who meet a dialog nobody opened and can't tell it from live content. Keyboard users can tab into it, and focus seems to vanish.

Take the dialog out of the render tree when it closes, with the hidden attribute, display: none, or by removing it. When it has to stay rendered, set aria-hidden="true" and inert on it until it opens again.

Severity: Moderate

Reported as: Forbidden interactive children; Nested interactive elements

A modal dialog's launcher must not contain, or be nested inside, another interactive element.

A button's children are presentational. When the launcher holds a link or another button, such as a dialog rendered inside it, screen reader users can't perceive or operate that control, and pointer users can't tell which one their click reaches.

Keep only the label inside the launcher, and place the dialog and any other controls outside it.

Severity: Serious

Reported as: Avoid aria-owns

A modal dialog and its launcher should not use aria-owns.

When the dialog owns content rendered elsewhere, some assistive technologies don't present it as part of the dialog, and it can stay inert with the page. When the launcher owns the dialog, the dialog's controls become presentational children of a button, and screen reader users can't operate them.

Move content that belongs in the dialog inside it, and keep the dialog outside the launcher. When the launcher needs to reference the dialog, use aria-controls.

Reported as: Focus kept within the modal

While a modal dialog is open, Tab and Shift + Tab must keep focus inside it, wrapping at the ends.

When Tab from the last control moves on to the page behind, focus lands somewhere the interface says is unavailable, often hidden by the overlay. Keyboard users press on looking for it, and can operate controls behind the dialog without realizing it.

Use showModal(), or handle both keys at the dialog: from the last tabbable element, Tab moves to the first, and from the first, Shift + Tab moves to the last. Find the tabbable elements on each press, so content added while the dialog is open is included.

Severity: Serious

Reported as: Could not simulate tab navigation

The Tab key should move focus between the interactive elements inside a modal dialog.

When the dialog's controls are generic elements with click handlers, or a focus trap cancels the Tab key without moving focus itself, focus stays where it landed. Keyboard users can't reach the other controls, often including the close button, and the dialog seems frozen.

Build the dialog's controls from native interactive elements, or give custom ones tabindex="0". When a handler intercepts Tab, have it move focus to the next or previous element rather than only blocking the default behavior.

Reported as: Keyboard accessible

A modal dialog's launcher must be reachable in the keyboard tab order.

When the launcher is built from markup that isn't focusable, such as a <div> or <span>, pointer users can open the dialog, but keyboard users can't reach the launcher or the task behind it.

Use a native <button> element, which is focusable by default, or give a custom launcher tabindex="0".

Severity: Critical

Reported as: Disabled element focusable

A disabled launcher should be out of the tab order, as a disabled native <button> is.

When a disabled custom launcher stays in the tab order, keyboard users land on a control that won't open its dialog.

Set tabindex="-1" on a custom launcher while aria-disabled="true" is set, and tabindex="0" when it's enabled again.

Severity: Minor

Reported as: Focusable offset

The element that carries the launcher's button role and opens the dialog must be the one that receives focus, not a descendant or a wrapper.

When another element takes focus instead, keyboard users can tab to the launcher but may not be able to open the dialog with Enter or Space.

Use a native <button>, or set tabindex="0" on the custom element that carries the role and handles activation.

Severity: Minor

Reported as: Focus management on modal close

Closing a modal dialog must return focus to the element that opened it.

When nothing restores focus, it drops to the document body and the tab order restarts at the top of the page. Keyboard users tab back through everything to find their place, and screen reader users have to work out where they were before they can go on.

Save a reference to the element that had focus before moving focus into the dialog, and call focus() on it after the dialog is hidden. Use the same path for every way of closing it, including the close button, Escape, and a submitted form. When the dialog's task leads to a next step, focus that step instead.

Severity: Serious

Reported as: Focus on modal open

Opening a modal dialog must move focus to an element inside it.

When focus stays on the launcher, the next Tab press moves through the page behind, and the focus indicator may be hidden by the overlay. Screen reader users get no sign the dialog opened and go on reading a page that no longer responds.

Move focus inside as part of opening, usually to the first focusable element. When the content has to be read first or would scroll out of view, put tabindex="-1" on the title or first paragraph and focus that. When the dialog confirms something hard to undo, set focus on the least destructive action.

Severity: Serious

Reported as: Focus on modal closed

Closing a modal dialog must leave focus on the launcher or, when the launcher is gone or the task continues elsewhere, on the next logical element.

When the dialog's action removes its launcher, the saved reference points at nothing and focus falls to the document body. Users lose their position and the context the dialog was part of. When the dialog completes a step that leads into another, returning to the launcher sends users back to where they started.

Decide the destination for each way of closing. When the launcher is gone, focus the nearest equivalent, such as the row after a deleted one. When the dialog leads into the next step of a task, focus that step even when the launcher is still there, making the element focusable if it isn't.

Severity: Moderate

Reported as: Modal background is not inert

While a modal dialog is open, everything outside it must be unavailable to operate and to read.

When the page behind is only dimmed, screen reader users who move by heading or landmark leave the dialog without noticing and carry on into the page, where controls may still respond. Content from the dialog and the page arrives in one sequence, and getting back means finding a dialog the page gives no sign of.

In the native construction, open the <dialog> element with showModal(), which makes everything outside it inert until it closes. In the custom construction, set inert on everything outside the dialog while it's open, and remove it when the dialog closes.

Severity: Serious

Reported as: Button not activated by keyboard

Keyboard users must be able to open a modal dialog from its launcher.

When a custom launcher responds only to click events from a pointer, keyboard users can reach it but can't open the dialog or complete its task.

Use a native <button> element, which is keyboard operable. For a custom launcher, add keyboard event listeners that open the dialog through the same handler as a click.

Severity: Critical

Reported as: Disabled button keyboard activation

A launcher that reports itself as disabled should not open its dialog from the keyboard.

When a custom launcher carries aria-disabled="true" but Enter or Space still opens the dialog, screen reader users are told the launcher is unavailable and then open its dialog anyway, so they stop trusting the states the interface reports.

Use a native <button>, which blocks activation when disabled is set, or block it in a custom launcher's handlers while aria-disabled="true" is set.

Severity: Serious

Reported as: Button requires space key activation

A custom launcher must open the dialog with the Space key, as a <button> element does, not only with Enter.

When only Enter works, users who press Space, as they would on any other button, conclude the launcher is unresponsive.

Use a native <button> element, or add a Space keyup handler to the custom launcher.

Severity: Minor

Reported as: Modal is not dismissed with Escape key

Pressing Escape must close a modal dialog from anywhere inside it.

When there's no handler, or the handler is attached to one control such as the close button, closing depends on finding that button. With the page behind inert, users who can't reach it have no way back.

Use showModal(), or listen for Escape on the dialog container so the press is caught wherever focus is. Treat it as cancel: discard unsaved input as the cancel button would, or ask first, and return focus as any other close does.

Severity: Moderate

Reported as: Deprecated keypress listener

A dialog's key handling should use keydown or keyup, not keypress.

When a handler listens for keypress, keys the browser doesn't send through that event go unanswered, and keyboard users find the dialog ignoring keys it's meant to respond to.

Replace each keypress listener with a keydown listener, and read the key from event.key.

Severity: Minor

The dialog's role, the launcher's role and name, the launcher's disabled state, and nothing interactive inside the launcher relate to 4.1.2 Name, Role, Value. The dialog's accessible name and its presence in the accessibility tree only while it's open relate to 1.3.1 Info and Relationships. Moving focus in and back out, keeping it inside, and making the page behind inert relate to 1.3.2 Meaningful Sequence. Reaching and activating the launcher by keyboard, and closing the dialog with Escape, relate to 2.1.1 Keyboard.

Three criteria map to no WCAG success criterion and are best practices: aria-modal on a custom dialog, removing a disabled launcher from the tab order, and ignoring the keyboard when the launcher is disabled.

Severity reflects how much an issue gets in users' way. Critical issues stop users outright: a dialog or launcher with the wrong role, a launcher with no name or one keyboard users can't reach or activate, or an open dialog that isn't exposed to assistive technology. Serious issues mislead users or let them stray out of the dialog, such as a page behind that isn't inert, focus that isn't moved in, kept in, or returned, or a wrong disabled state on the launcher.

Moderate issues make users work harder, such as a dialog with no name, a closed dialog left in the accessibility tree, or no Escape key. Minor issues break a convention without blocking the task, such as a missing aria-modal or a launcher that ignores the Space key. Three checks carry no severity: the general check for aria-owns and the sanity checks on where the role sits and on Tab moving focus.