A modal dialog is a window that opens over the page and blocks everything behind it until it closes. Five things make one work. Focus moves into it when it opens, stays inside while it is open, Escape closes it, and focus returns to the page where the reader left it. The fifth is an accessible name, which ARIA requires in as many words. The native dialog element opened as a modal does four of the five for you with no JavaScript of your own. It chooses the initial focus and honours an autofocus where you set one. It contains the tab sequence, makes the rest of the document inert, closes on Escape unless you have asked it not to, and restores focus to the element that had it before. The name is the one that is still yours to write.
In practice
The browser's default choice of initial focus is defensible rather than ideal, which is why you override it on purpose. W3C's pattern gives four cases. The first focusable element, usually. The least destructive control where the dialog finishes something you cannot undo. A static element at the start of the content where the dialog holds structure somebody has to read, such as a list or a table. And the control people will actually reach for, such as an OK button, where the dialog only tells them something.
Marking a dialog modal is a claim, and making it falsely is worse than not making it at all. W3C sets two conditions before you may. Your code has to stop everybody interacting with the content outside it, and the styling has to obscure that content. A banner that announces itself as modal, dims the page, and still lets a mouse user click straight through it has stranded a screen reader user who was told there is nothing else there.
Two limits on the native element are worth knowing. A modal opened inside an iframe blocks its own document and leaves the page around it interactive. And there is a separate role for the dialog that interrupts with something urgent, which is often the right home for a confirmation somebody cannot undo, though a plain dialog is the right answer far more often than teams reach for it.
Why it matters
It is the most-failed component we test, and it sits inside the category screen reader users put second only to CAPTCHA in WebAIM's survey, interactive elements that do not behave as expected. That category is wider than dialogs, so read it as the neighbourhood rather than the address. The failure is severe rather than annoying. Somebody who cannot leave a dialog cannot continue and cannot go back, which is a Level A failure under the no keyboard trap rule and one of the few that strands a person completely. What makes it frustrating is how much of it is already solved. Use the native element and four of the five jobs are done before you write a line.
Where focus should land
The first field in a form dialog. The safest control in a confirmation, so a mistaken Enter deletes nothing. The heading itself where the dialog holds a table or a list somebody has to read from the top. And in a dialog that only tells you something, the button they came to press.
Where this shows up on the site
Related terms
- Focus trapA focus trap is somewhere on a page that keyboard focus can get into and not out of.
- FocusFocus is the one place on a page that is currently taking keyboard input.
- Keyboard accessibilityKeyboard accessibility means every piece of functionality on the page can be operated through a keyboard interface.
- Accessible nameThe accessible name is what assistive technology announces an element as, the words a screen reader speaks when it lands on a button or a link.
- Cookie bannerA cookie banner is the overlay asking permission to set cookies, and it is usually a vendor script laid over the top of a finished page.
- alertdialogAn alertdialog is a dialog that interrupts, and it is the role for a message somebody has to answer before anything else happens.
- Change of contextA change of context is one of four things, and only four.
Knowing the word is the easy part.
Find out where your own site stands. The free scan checks 10 pages in a real browser against all 90 supported automated rules, separates 27 best-practice checks from its WCAG findings, and names the rule behind every result.