HTML Tips: When to Use <dialog>, <details>, or a Custom Div for Overlays

November 17, 2026

Not every overlay is a modal. A confirmation that blocks the page, a small “show more” disclosure, a non-modal command menu, and a draggable widget all have different interaction contracts. Picking the right HTML element matters because semantics, focus behavior, Escape handling, and browser support come bundled—or don’t.

modal dialog interface

Start with the interaction, not the visual design

The most common mistake is reaching for a positioned <div> because the Figma frame is centered and blurred. Visual placement tells you very little. Ask these questions instead:

  • Must the user finish or dismiss this before continuing?
  • Is it just progressive disclosure of extra content?
  • Should it stay lightweight and non-modal, like a command palette or custom menu?
  • Does the interaction need behavior that no native overlay model provides?

That order usually points you to <dialog>, <details>, the Popover API, or a carefully built custom container.

accessible web form

Quick decision table

  • Blocking task: use dialog.showModal(). Examples: destructive confirmations, required forms, task-focused editors.
  • Show more content: use <details>. Examples: FAQ answers, optional help text, inline advanced filters.
  • Non-modal lightweight overlay: prefer the Popover API where support fits. Examples: command menus, toast-like surfaces, pickers that should not block the whole page.
  • Custom interaction model: use a neutral <div> plus the correct ARIA and keyboard behavior. Examples: draggable panels, highly custom widgets, mixed canvas tools.

Use <dialog> for real modal work

A native modal dialog is the right choice when the overlay creates a mode: while open, the page behind is inert, keyboard users stay within the task, and Escape provides a standard exit. The key is opening it with showModal(), not show().

showModal() renders the dialog in the top layer, gives it the appropriate modal semantics, and lets you style the page-level background with ::backdrop. Calling show() creates a non-modal dialog; it does not provide the same blocking behavior.

A runnable dialog pattern

<dialog id="confirm" aria-labelledby="confirm-title" aria-describedby="confirm-desc">
  <h2 id="confirm-title">Delete draft?</h2>
  <p id="confirm-desc">This will remove the draft permanently.</p>

  <form method="dialog">
    <button value="cancel">Keep editing</button>
    <button id="delete-btn" value="delete" formmethod="dialog">Delete</button>
  </form>

  <button id="close-x" aria-label="Close">×</button>
</dialog>

<button id="open-btn">Delete draft</button>

<script>
  const dialog = document.querySelector('#confirm');
  const openBtn = document.querySelector('#open-btn');

  openBtn.addEventListener('click', () => dialog.showModal());

  dialog.querySelector('#close-x').addEventListener('click', () => {
    dialog.close('cancelled');
  });

  dialog.addEventListener('cancel', (event) => {
    // Fired for Escape. Prevent it if the modal must require an explicit choice.
    console.log('Escape pressed');
  });

  dialog.addEventListener('close', () => {
    console.log('Closed with:', dialog.returnValue);
  });
</script>

Buttons inside <form method="dialog"> close the dialog without submitting the page. Their value becomes dialog.returnValue, which is handy for confirming which action closed it.

Backdrop clicks need care

You can detect clicks on the backdrop by checking whether the click target is the dialog itself:

dialog.addEventListener('click', (event) => {
  if (event.target === dialog) {
    dialog.close('backdrop');
  }
});

Do not assume that a backdrop click always means “cancel.” In a destructive flow, accidentally clicking outside can be just as bad as accidentally pressing Escape. Some teams allow backdrop dismissal for low-risk dialogs; others reserve it for explicit close actions. Also, padding on the <dialog> can make the click target behave differently from the visible rounded box, so test the hit area.

Customization limits

Native dialogs are styleable: you can control borders, radius, shadows, padding, animations, and ::backdrop. The browser gives you focus behavior and top-layer rendering for free. The tradeoff is that advanced entrance choreography and some nested overlay patterns need extra testing, especially when older browser support matters.

Use <details> for disclosure, not fake modals

<details> is for showing and hiding optional content under a visible summary. It is perfect when the user asks “what does this mean?” or expands an optional section. The browser manages the open state, and the disclosure pattern is familiar to assistive technology.

<details class="popover-like">
  <summary>Advanced filters</summary>
  <div class="panel">
    <label><input type="checkbox"> Show archived</label>
    <label><input type="checkbox"> Only starred</label>
  </div>
</details>
.popover-like {
  position: relative;
  display: inline-block;
}

.popover-like .panel {
  position: absolute;
  inset-inline-start: 0;
  margin-block-start: .5rem;
  padding: .75rem 1rem;
  border: 1px solid #d4d4d8;
  border-radius: .75rem;
  background: white;
  box-shadow: 0 12px 30px rgb(0 0 0 / .12);
  z-index: 10;
}

.popover-like[open] .panel {
  animation: pop .12s ease-out;
}

@keyframes pop {
  from { opacity: 0; transform: translateY(-4px); }
  to { opacity: 1; transform: translateY(0); }
}

This looks like a small popover, but it is still a disclosure. It does not render in the top layer, does not create a backdrop, does not trap focus, and does not provide outside-click dismissal. If your panel needs collision detection, escape handling beyond simple toggling, focus restoration into a menu, or closure when the user clicks elsewhere, <details> is being stretched too far. Move to dialog.showModal() for a blocking task or Popover for a non-modal floating surface.

Prefer Popover for non-modal command surfaces

If you are building a command menu, color picker, toolbar bubble, or toast-style surface that should appear above content without blocking the whole page, look at Popover first. It gives top-layer rendering and light-dismiss behavior without inheriting modal semantics.

<button popovertarget="commands">Open commands</button>
<div id="commands" popover>
  <input type="search" placeholder="Type a command" />
</div>

Popover is not a universal replacement for dialog. A destructive confirmation that requires a decision should still be a modal dialog, because the user needs the stronger interaction boundary.

When a custom div is justified

A plain <div> is a neutral container, not an accessible overlay by itself. It becomes reasonable when the native models do not match the actual widget behavior.

Good custom-div cases include:

  • Toasts: use an appropriate live region, such as aria-live="polite" or role="status", and avoid stealing focus unless the message requires action.
  • Draggable floating widgets: a palette or inspector panel can be a generic container if it remains non-modal and its controls remain in normal tab order.
  • Complex command menus: if Popover support or behavior is insufficient, build the menu with the correct menu/combobox/listbox semantics and full keyboard navigation.

The bad case is the classic centered box with a close icon and a semi-transparent background but no role, no focus move, no focus trap, and no Escape handling. If it looks and behaves like a modal, it must not be an unlabeled div.

Minimum accessibility requirements for a custom modal

If you genuinely must build a modal on a div, the minimum checklist is:

  1. Use role="dialog", or role="alertdialog" for an urgent message with a required action.
  2. Set aria-modal="true", while still making the background inert because the attribute alone does not reliably remove all keyboard or screen-reader access.
  3. Add aria-labelledby for the title and aria-describedby for supporting text when present.
  4. Move focus into the dialog when it opens, usually to the first safe control or the close button.
  5. Keep Tab and Shift+Tab cycling inside the dialog.
  6. Close on Escape and stop or handle the event according to the dialog’s rules.
  7. Make the background inert with the inert property or a robust polyfill pattern.
  8. Return focus to the triggering control after closing.

That list is precisely why dialog.showModal() is usually cheaper: the browser already handles much of this behavior. A custom div means you own the edge cases—nested portals, scroll locks, iOS focus quirks, screen-reader virtual cursors, and restoration after unmount.

A simple decision flow

Use this shortcut during implementation:

  1. Does it block the page until resolved? Use <dialog> with showModal().
  2. Does it simply reveal more content? Use <details>.
  3. Is it a non-modal floating menu or lightweight surface? Try Popover first.
  4. Do none of those interaction models fit? Use a div, add the correct ARIA, and implement focus and keyboard behavior explicitly.

The goal is not to avoid every div. The goal is to avoid using a div to reinvent behavior that the browser already provides with better semantics and fewer accessibility gaps.