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-popupandaria-controlsare 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:
- automatically
inerts other elements, - prevents users from tabbing into other elements, and
- 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:
- set
aria-expandedback tofalseon the invoking trigger, - close the modal with the
closemethod, - 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.



