Guides

Why my modal breaks keyboard focus — and how one tag fixes it

Illustration: a window above the page, with the focus thread slipping past it

The symptom is familiar. The modal opens and looks perfect. You press Tab — and the focus ring wanders off behind the dim overlay, strolling through links on the page underneath. Esc doesn't close it. And when the window finally does close, focus lands at the top of the document.

With a mouse everything works flawlessly, which is why this bug is so easy to miss.

It's not a minor thing: in the WebAIM survey, "interactive elements like menus, tabs and dialogs that do not behave as expected" is the second most painful item of all, right after CAPTCHA. The good news: three causes cover almost every case, and the first is fixed by one tag.

Cause 1. It isn't a dialog, just a block on top of the page

The most common one, and nearly guaranteed in generated code. The modal is built like this:

<div class="modal">…</div>

Visually a modal: dim backdrop, shadow, centre of the screen. To the browser, an ordinary block drawn on top. The page underneath is alive: its links and buttons are still in the Tab order, and the keyboard happily walks over there. "Covered" is an illusion created by the dimming.

How to check: open the modal and press Tab while watching the screen. If the focus ring vanishes from the window, that's your cause. If you can't see a ring at all, look for outline: none in your styles first.

How to fix. HTML has an element that does all of this for you:

<dialog id="d">
  <h2>Confirm deletion</h2>
  <button autofocus>Cancel</button>
</dialog>
document.getElementById('d').showModal();

Specifically showModal(), not show() and not the open attribute. For that one line, the browser gives you:

  • the rest of the page made inert — Tab won't go there;
  • Esc to close;
  • focus moved inside the window on open;
  • correct announcement to screen readers.

The subtlety people trip on: show() and the open attribute open a non-modal window. It looks identical and behaves like an ordinary block — Esc does nothing, the page behind stays active. If you already use <dialog> and focus still leaks, this is almost certainly why.

Cause 2. Focus never moved inside on open

The window appeared, but focus stayed on the button that opened it, somewhere deep in the page. A person using a screen reader won't even know anything happened: they're still listening to the old spot.

How to check: open the modal from the keyboard (Enter on the button) and, without pressing anything else, see where the focus ring is. It belongs inside the window.

How to fix: put autofocus on the element the person will interact with first. In a confirmation dialog, that's the safe button ("Cancel"), not "Delete." If the content is long and its beginning matters, give the window title tabindex="-1" and focus that — the text will then be read from the start.

Don't put tabindex on the <dialog> itself: it isn't interactive and shouldn't take focus.

Cause 3. Focus never came back after closing

The most forgotten one. You close the window and find yourself at the top of the page. Invisible with a mouse, disastrous with a keyboard: someone pressed "Delete" on row 37 of a list and got thrown into the site header.

The rule is simple: when a dialog closes, focus returns to the element that opened it. One exception — if that element is gone: you deleted a row, so send focus somewhere sensible, like the next row.

How to fix: remember the active element before opening and restore focus after closing.

let opener;
btn.addEventListener('click', () => { opener = document.activeElement; d.showModal(); });
d.addEventListener('close', () => opener?.focus());

Three lines. They're almost never in generated code — because visually everything already works.

A one-minute check: four keystrokes

The order is chosen so each cause surfaces in turn. Don't touch the mouse at all — the whole bug lives on the keyboard.

  1. Tab to the opening button and press Enter. Modal open? Look at where the focus ring is — that's cause 2.
  2. Press Tab about ten times. Focus must stay inside the window and wrap from the last element back to the first. Escaped outside — cause 1.
  3. Press Esc. Nothing happened — almost certainly cause 1 again: it isn't a modal dialog.
  4. See where focus lands after closing. Not on the button that opened it — cause 3.

Pass all four and your window is fine. Usually one of the four fails on the first try.

Two more things worth checking

  • A visible close button inside the window. Not just an X drawn with a pseudo-element, but a real button in the Tab order. Esc shouldn't be the only way out.
  • A name for the window. Link the title with aria-labelledby so opening announces "dialog, Confirm deletion" rather than just "dialog."

Why doesn't normal testing catch this?

Because a mouse can't reproduce it: a click always lands where you aim. It only exists on the keyboard. The fast check is walking the flow with a screen reader, or simply taking your hand off the mouse.

Can I do it without <dialog>?

You can, but you'll have to reproduce everything it gives you: mark the background inert, cycle Tab inside the window, handle Esc, move focus in and back out. Libraries do this — but start with the built-in element.

What if several modals are open?

Esc should close only the last one opened, not all of them. With <dialog> the browser handles that itself — one more reason not to invent your own.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →