Modal / Dialog

Last updated:

When to use native dialog and popover, how to manage focus, and when a full page is the better choice.

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.

The native dialog element and popover APIs already provide semantics, focus handling, keyboard behaviour, and accessibility support. Use that work — do not rebuild modal systems from scratch for emotional reasons.

<dialog id="confirm-delete">
    <form method="dialog">
        <h2>Delete this invoice permanently?</h2>
        <p>This cannot be undone.</p>
        <button type="submit" value="cancel">Cancel</button>
        <button type="submit" value="confirm">Delete</button>
    </form>
</dialog>

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
  • trap focus for modal dialogs — but always allow Escape where appropriate
  • return focus to the triggering control when the dialog closes
  • provide a visible, obvious close control — not a hidden icon

Users expect Escape to close dialogs unless the action is genuinely destructive or legally sensitive. Make it clear whether closing loses progress and whether actions are reversible.

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?

When you need a modal overlay with focus management and Escape to close. Prefer dialog or popover before building custom overlays with divs and tabindex hacks.

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.