HTML Tips: When to Use <dialog>, <details>, or a Custom ARIA Popup

November 21, 2026

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.

web accessibility keyboard

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.

modal dialog interface

Three-column decision table

Question<dialog><details>Custom ARIA popup
PurposeModal or non-modal dialog windowNative disclosure of related contentDropdown, popover, combobox, or desktop-style menu
Blocks page?showModal() yes; show() noNoUsually no; implement modal behavior only if required
Top-layer floating?Modal dialog yesNo; it participates in normal flowNot automatically; use positioning, popover, or portal carefully
JS dependencyMinimal for open/close; more for forms/focusNone for basic disclosureRequired for focus, keyboard, outside click, and state
Focus managementModal has built-in inert background and initial focus rulesFocus stays on <summary>You must move, trap, restore, or rove focus deliberately
Escape / outside clickEscape closes modal; backdrop click does not unless you code itUsually not expected; toggle through summaryYou define and implement both
Good examplesConfirm delete, focused form, critical alertFAQ, optional settings text, inline expandable sectionAccount actions, filter dropdown, custom select, app menu
Avoid forNavigation menus or inline helpTooltips, modals, complex menus needing arrow-key semanticsSimple 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

  1. Operate every popup with keyboard alone: Tab, Enter, Space, Escape, and arrow keys where promised.
  2. Verify visible focus is never lost and focus returns to the trigger after a menu selection or cancel.
  3. Check contrast for borders, text, the backdrop, and the open/closed affordance.
  4. Test with one screen reader, not just accessibility-tools labels.
  5. Confirm modal dialogs block background interaction and non-modal dropdowns do not.
  6. Test viewport edge cases, zoom to 200%, and long content.
  7. Audit aria-controls, IDs, hidden, and aria-expanded after dynamic updates.
  8. Decide outside-click behavior explicitly; never make it the only way to close something.