01 — Foundation

Interrupt carefully

Dialogs are powerful — which means they are also dangerous.

A modal takes focus, changes flow, and demands attention. Done well, it feels focused and useful. Done badly, it feels like the interface has taken someone hostage.

This pattern defines practical expectations for accessible, resilient dialog behaviour — real usability and restraint, not overlay theatre.

02 — When

When a dialog is justified

Interruptions should earn their place.

Use a dialog when users must

  • confirm important or destructive actions
  • complete a short, focused task
  • review critical information before continuing
  • make a decision that blocks the page behind

Do not use a dialog for

  • marketing interruptions or unnecessary announcements
  • content that could live inline on the page
  • decorative complexity or “we had space for a overlay”

03 — Platform

Use the platform first

Prefer native APIs before building a custom modal stack.

A native dialog opened with showModal()provides modal semantics, moves focus inside, and makes the rest of the page inert. Give it an accessible name and choose an appropriate initial focus. A popover is non-modal and does not automatically provide dialog or menu semantics.

<button type="button" id="open-confirmation" hidden>
    Review deletion
</button>
<a href="/invoices/123/delete/" id="confirmation-fallback">
    Review deletion on a separate page
</a>

<dialog id="confirm-delete" aria-labelledby="confirm-delete-title">
    <form method="dialog">
        <h2 id="confirm-delete-title">Delete this invoice permanently?</h2>
        <p>This cannot be undone.</p>
        <button type="submit" value="cancel" autofocus>Cancel</button>
        <button type="submit" value="confirm">Delete</button>
    </form>
</dialog>
const trigger = document.getElementById('open-confirmation');
const dialog = document.getElementById('confirm-delete');
const fallback = document.getElementById('confirmation-fallback');

if (trigger && dialog && fallback && typeof dialog.showModal === 'function') {
    trigger.addEventListener('click', () => {
        dialog.returnValue = '';
        dialog.showModal();
    });

    dialog.addEventListener('close', () => {
        trigger.focus();
    });

    trigger.hidden = false;
    fallback.hidden = true;
}

The fallback URL represents a server-rendered confirmation page; replace it with a real route. Without JavaScript, that link remains available. This example only returns a choice: method="dialog"closes the dialog without sending a request. Only an explicitconfirm result should lead to an authorised server-side deletion. Cancel and Escape must never delete anything.

The close handler restores focus explicitly, including after pointer activation in browsers that do not focus buttons when clicked. If a completed action removes the trigger, move focus to the next logical control instead.

See W3C's native dialog technique for focus, naming, and keyboard expectations.

Declarative dialog commands

Where your tested browser baseline supports invoker commands,commandfor identifies the dialog and commandsupplies the action. This supplementary help dialog opens and closes without a JavaScript click handler:

<button type="button" commandfor="export-help" command="show-modal">
    Export help
</button>

<dialog id="export-help" aria-labelledby="export-help-title">
    <h2 id="export-help-title">Exporting your invoices</h2>
    <p>Choose a date range, then select Download CSV.</p>
    <button type="button" commandfor="export-help" command="close" autofocus>
        Close
    </button>
</dialog>

For older browsers, use the guarded showModal()enhancement and page fallback above. Test command support with'commandForElement' in HTMLButtonElement.prototype; support for dialog alone is not enough. Do not attach both a declarative opener and an unconditional JavaScript opener.

Support checked 4 October 2026: invoker commands are Baseline Newly available. Check newer additions separately: closedby still has limited availability. It controls dismissal behaviour; it does not replace an accessible name or a visible Cancel or Close control.

04 — Popover

Dialog vs popover

These are not the same thing — choose based on how much you are interrupting.

Dialog

  • focused tasks, confirmations, and short forms
  • blocking interaction until the user addresses the overlay

Popover

  • menus, lightweight context, and supplementary content
  • non-blocking UI that should not behave like a surprise mini-modal

05 — Focus

Focus, escape, and close controls

Broken focus handling is an accessibility failure immediately.

  • move focus into the dialog when it opens
  • keep focus within the modal using native behaviour; allow Escape to cancel
  • return focus to the triggering control when the dialog closes
  • provide a visible, obvious close control — not a hidden icon

Escape should cancel a destructive confirmation. The risk of the action is a reason to make cancellation clear and easy. For forms with unsaved changes, explain what closing does and preserve drafts where practical. Do not disable Escape simply because a task is sensitive.

06 — Overlay

Overlay, scroll, and sizing

Background behaviour and dialog size should match user expectations.

  • disable background interaction for modal dialogs; keep non-modal overlays predictable
  • lock body scroll carefully — avoid jumps, layout shift, and mobile Safari quirks
  • size dialogs for the task — not fullscreen for tiny actions or microscopic for complex flows
  • if content is huge, scroll-heavy, or workflow-complex, use a page instead

07 — Confirmations

Confirmations and destructive actions

Be specific — vague copy causes mistakes.

Too vague

'Are you sure?'

Clearer

'Delete this invoice permanently?'

Destructive dialogs should explain what will happen, whether recovery exists, and whether the action is permanent. Users should not gamble during destructive actions.

08 — Forms

Forms, accessibility, and motion

Forms inside dialogs need extra care — and motion should orient, not perform.

  • manage focus, validation, errors, and keyboard submission inside the overlay
  • expose correct semantics and announce the dialog appropriately
  • remain readable at zoom; avoid motion-heavy entrances
  • avoid multi-step form monsters trapped inside overlays
@media (prefers-reduced-motion: reduce) {
    * {
        animation-duration: 0.01ms !important;
        transition-duration: 0.01ms !important;
    }
}

09 — Resilience

Mobile, enhancement, and performance

Sometimes the right answer is a full page — especially on mobile.

  • large enough close targets and actions that are not clipped on small screens
  • critical confirmations and forms should survive JavaScript problems where possible
  • avoid giant overlay frameworks, nested modals, and div-based fake dialogs
  • do not use modals for marketing interruptions nobody asked for

10 — Review

Before you approve

A short checklist for dialogs in code review.

  • does this truly need a dialog — or should it be a popover or page?
  • is focus trapped, restored, and visible throughout?
  • does Escape work sensibly and are close actions obvious?
  • is background interaction and scroll behaviour correct?
  • is the dialog usable on mobile and fully accessible?

When in doubt, ask: Is this helping users complete a focused task, or interrupting them because the design team got excited? If the answer is excitement, remove the modal.

Common questions

When should I use a native dialog element?

Use a dialog opened with showModal() when a focused task needs a modal overlay, focus management, and Escape to cancel. Give it an accessible name. Popovers are non-modal and suit supplementary content or actions.

Should every modal trap focus?

Modal dialogs should trap focus while open and restore focus to the trigger on close. Non-modal panels may not need a trap — do not trap by default everywhere.

When is a full page better than a modal?

Long forms, multi-step flows, and content users may bookmark or share are usually better as dedicated routes than cramped overlays.