How Popovers and Dialogs Relate

The two APIs overlap enough to confuse most developers, but the containment is simple: dialogs are a subset of popovers, and modal dialogs are a subset of dialogs. That's why the Popover API can be applied to a <dialog> element itself.

The visual split is equally clear. Modals should show a backdrop; popovers should not. Styling a popover's ::backdrop pseudo-element signals that the popover is a dialog, which drags in a whole can of problems. Reserve ::backdrop styling for modals only.

The Popover API and Its Built-In Accessibility

A popover takes three pieces of markup: a popovertarget attribute on the trigger, an id on the popover, and a popover attribute on the popover. The popovertarget value must match the id.

<!-- Using popover on a dialog element --> 
<dialog popover>...</div> 

Wrapping the popover in a <dialog> element to get the dialog role is optional but recommended, since most popovers really are dialogs and dialog is a strong default role.

<button popovertarget="the-popover"> ... </button>
<dialog popover id="the-popover"> The Popover Content </dialog>

Those few lines carry a substantial amount of accessibility for free:

  • Focus management — focus moves into the popover on open and returns to the trigger on close.
  • ARIA wiring — aria-expanded, aria-popup and aria-controls are handled natively by browsers.
  • Light dismiss — clicking outside or pressing Esc closes the popover.

Unstyled, the result looks unremarkable; styling is a separate subject.

Where the Dialog API Falls Short — and Where It Wins

The Dialog API ships with none of that by default: no automatic focus management, no ARIA connection, no light dismiss. Each has to be built in JavaScript. On nearly every axis, this makes the Popover API the stronger choice — with one exception: modals.

The Dialog API's showModal method creates a modal and then:

  1. automatically inerts other elements,
  2. prevents users from tabbing into other elements, and
  3. prevents screen readers from reaching other elements.

It does this so effectively that focus trapping inside the modal is no longer necessary. The trade-off is that focus handling and ARIA become the developer's job.

Building an Accessible Modal by Hand

Start from an HTML scaffold. The markup deliberately omits aria-expanded: this keeps the HTML simpler, lets everything that doesn't work without JavaScript (the ARIA attributes and focus behavior) live in JavaScript, and keeps the markup reusable.

<button 
  class="modal-invoker" 
  
  aria-haspopup="dialog"
>...</button>

<dialog id="the-modal">The Popover Content</dialog>

The implementation below is vanilla JavaScript; React, Svelte and other frameworks will need adjustments, though they should be straightforward.

Initial state

Loop through every dialog-invoker and set aria-expanded to false, then point aria-controls at the <dialog> element. aria-controls is a weak attribute, but there's no better way to connect these elements and no harm in doing so.

const modalInvokers = Array.from(document.querySelectorAll('.modal-invoker'))

modalInvokers.forEach(invoker => {
  const dialogId = invoker.dataset.target
  const dialog = document.querySelector(`#${dialogId}`)
  invoker.setAttribute('aria-expanded', false)
  invoker.setAttribute('aria-controls', dialogId)
})

Opening

On click of the invoker, flip aria-expanded from false to true so assistive tech users are told the modal is shown, then call showModal. No hiding code is needed in this handler: once the dialog is open, the invoker can't be clicked.

modalInvokers.forEach(invoker => {
  // ... 

  // Opens the modal
  invoker.addEventListener('click', event => {
    invoker.setAttribute('aria-expanded', true)
    dialog.showModal()
  })
})

Closing

showModal provides no light dismiss, so a user can't close the modal by clicking the overlay or pressing Esc. A dedicated close button inside the modal content is therefore required.

<dialog id="the-modal"> 
  <button class="modal-closer">X</button>
  <!-- Other modal content -->
</dialog>

The close handler does three things:

  1. set aria-expanded back to false on the invoking trigger,
  2. close the modal with the close method,
  3. return focus to the invoker element.
modalInvokers.forEach(invoker => {
  // ... 

  // Opens the modal
  invoker.addEventListener('click', event => {
    invoker.setAttribute('aria-expanded', true)
    dialog.showModal()
  })
})

const modalClosers = Array.from(document.querySelectorAll('.modal-closer'))

modalClosers.forEach(closer => {
  const dialog = closer.closest('dialog')
  const dialogId = dialog.id
  const invoker = document.querySelector(`[data-target="${dialogId}"]`)
  
  closer.addEventListener('click', event => {
    dialog.close()
    invoker.setAttribute('aria-expanded', false)
    invoker.focus()
  })
})

Popover API for Modals and the Road Ahead

You can build a modal with the Popover API, but you'll implement inerting for other elements and focus trapping yourself, which is more work than the aria-expanded, aria-controls and focus bookkeeping the Dialog API demands.

A proposal for invoker commands aims to bring popovertarget-style declarative behavior to the Dialog API, which would simplify modal construction in the future. Until then, the accessibility patching described above remains necessary.

Guiding Rule

Use the Popover API for most popovers; reach for the Dialog API only for modal dialogs. There's no need to use both — one will do.