Pick the pattern before picking the widget
The most common popup bug starts with markup chosen too late. A confirmation that blocks the page is not the same component as an FAQ answer, and neither is the same as an action menu. Start with user intent, then choose <dialog>, <details>, or a custom ARIA disclosure.

Current browser support is good for HTMLDialogElement.showModal(), the top layer, and ::backdrop in modern Chrome, Edge, Firefox, and Safari. The name attribute for exclusive <details> accordions is newer; check your target browsers before relying on it. The ARIA menu pattern is well defined, but it is frequently used where a normal disclosure dropdown would be simpler.

Three-column decision table
| Question | <dialog> | <details> | Custom ARIA popup |
|---|---|---|---|
| Purpose | Modal or non-modal dialog window | Native disclosure of related content | Dropdown, popover, combobox, or desktop-style menu |
| Blocks page? | showModal() yes; show() no | No | Usually no; implement modal behavior only if required |
| Top-layer floating? | Modal dialog yes | No; it participates in normal flow | Not automatically; use positioning, popover, or portal carefully |
| JS dependency | Minimal for open/close; more for forms/focus | None for basic disclosure | Required for focus, keyboard, outside click, and state |
| Focus management | Modal has built-in inert background and initial focus rules | Focus stays on <summary> | You must move, trap, restore, or rove focus deliberately |
| Escape / outside click | Escape closes modal; backdrop click does not unless you code it | Usually not expected; toggle through summary | You define and implement both |
| Good examples | Confirm delete, focused form, critical alert | FAQ, optional settings text, inline expandable section | Account actions, filter dropdown, custom select, app menu |
| Avoid for | Navigation menus or inline help | Tooltips, modals, complex menus needing arrow-key semantics | Simple native cases, or menus where ARIA promises more than you implement |
Use <dialog> when the task must take over
Reach for a modal dialog when the user must complete or dismiss a task before returning to the page. Use showModal(), not a pile of z-index overrides. The browser places the modal in the top layer, gives it a ::backdrop, and makes the rest of the page inert.
<dialog id="confirm-dialog" aria-labelledby="confirm-title">
<h2 id="confirm-title">Delete draft?</h2>
<p>This action cannot be undone.</p>
<form method="dialog">
<button value="cancel">Cancel</button>
<button value="delete">Delete</button>
</form>
</dialog>
<button id="open-confirm">Delete draft</button>
<script>
const opener = document.querySelector('#open-confirm');
const dialog = document.querySelector('#confirm-dialog');
opener.addEventListener('click', () => {
dialog.returnValue = '';
dialog.showModal();
});
dialog.addEventListener('close', () => {
if (dialog.returnValue === 'delete') {
// perform deletion
}
});
</script>
For long dialogs, set focus on the first meaningful control or the dialog heading container depending on the flow. Do not automatically focus the destructive button. If clicking the backdrop should close, check that the click target is the dialog itself.
dialog.addEventListener('click', (event) => {
if (event.target === dialog) dialog.close();
});
Don't do this
- Don't use
show()when you need a modal; it opens a non-modal dialog. - Don't nest several modals unless the product truly requires it.
- Don't assume backdrop click closes anything; that is author behavior.
Use <details> for inline disclosure
<details> is the cheapest accessible pattern when content simply expands in place. The browser manages aria-expanded-like state on the summary and keyboard activation with Enter or Space.
<details class="help-panel">
<summary>Which file formats can I upload?</summary>
<div class="help-panel__body">
<p>You can upload PNG, JPEG, WebP, or PDF files up to 10 MB.</p>
</div>
</details>
Use the name attribute when you want a native exclusive accordion group, but treat it as progressive enhancement if older browsers matter:
<details name="faq">…</details>
<details name="faq" open>…</details>
<details name="faq">…</details>
Don't do this
- Don't put critical form fields only inside a collapsed disclosure unless users will reliably find them.
- Don't restyle the marker away without providing a visible replacement affordance.
- Don't force it closed on Escape unless your design promises popup behavior; users generally expect disclosure state to persist.
Custom ARIA popup: start with a non-modal disclosure dropdown
For an ordinary actions menu, use a disclosure button and a normal list. It is easier to build correctly than role="menu", and screen-reader users can navigate it with familiar button and link semantics.
<div class="dropdown">
<button
type="button"
class="dropdown__trigger"
aria-expanded="false"
aria-controls="article-menu"
>
More actions
</button>
<div id="article-menu" class="dropdown__panel" hidden>
<ul>
<li><a href="/edit/42">Edit</a></li>
<li><button type="button" data-action="duplicate">Duplicate</button></li>
<li><button type="button" data-action="archive">Archive</button></li>
</ul>
</div>
</div>
CSS owns visual presentation: positioning, animation, shadows, and showing or hiding the panel. The hidden attribute remains the authoritative non-visual hidden state.
.dropdown { position: relative; }
.dropdown__panel {
position: absolute;
top: calc(100% + 4px);
left: 0;
min-width: 10rem;
background: #fff;
border: 1px solid #cbd5e1;
border-radius: 8px;
box-shadow: 0 12px 30px rgb(15 23 42 / .15);
}
.dropdown__panel[hidden] { display: none; }
JavaScript owns behavior and accessibility state: open, close, focus movement, outside clicks, and focus restoration.
const root = document.querySelector('.dropdown');
const trigger = root.querySelector('.dropdown__trigger');
const panel = root.querySelector('.dropdown__panel');
const items = root.querySelectorAll('a, button');
function openMenu() {
panel.hidden = false;
trigger.setAttribute('aria-expanded', 'true');
items[0]?.focus();
}
function closeMenu(restoreFocus = true) {
panel.hidden = true;
trigger.setAttribute('aria-expanded', 'false');
if (restoreFocus) trigger.focus();
}
trigger.addEventListener('click', () => {
panel.hidden ? openMenu() : closeMenu();
});
items.forEach((item) => {
item.addEventListener('click', () => closeMenu(true));
});
document.addEventListener('click', (event) => {
if (!root.contains(event.target)) closeMenu(false);
});
document.addEventListener('keydown', (event) => {
if (panel.hidden) return;
if (event.key === 'Escape') {
event.preventDefault();
closeMenu(true);
}
if (event.key === 'Tab') {
closeMenu(false);
}
});
This version moves focus into the panel on open. If your product convention keeps focus on the trigger, leave focus there, make Tab reach panel items in DOM order, and toggle aria-expanded consistently. The important part is that focus never becomes invisible or trapped.
When role="menu" is actually appropriate
Use role="menu", role="menuitem", ArrowDown, ArrowUp, Home, End, Escape, and roving tabindex for desktop-style action bars such as File / Edit / View. Do not use it for a generic list of links. If you keep that pattern, every menuitem except the active one needs tabindex="-1", and arrow keys must move the roving tabindex and focus.
Don't do this
- Don't add
role="menu"just because the visual design says “menu”. - Don't close only on outside pointer clicks; keyboard users need Escape and logical Tab behavior.
- Don't leave focus on a removed element after selection; return focus to the trigger or move it deliberately.
Publish checklist
- Operate every popup with keyboard alone: Tab, Enter, Space, Escape, and arrow keys where promised.
- Verify visible focus is never lost and focus returns to the trigger after a menu selection or cancel.
- Check contrast for borders, text, the backdrop, and the open/closed affordance.
- Test with one screen reader, not just accessibility-tools labels.
- Confirm modal dialogs block background interaction and non-modal dropdowns do not.
- Test viewport edge cases, zoom to 200%, and long content.
- Audit
aria-controls, IDs,hidden, andaria-expandedafter dynamic updates. - Decide outside-click behavior explicitly; never make it the only way to close something.