canon-modals

CANON · Modals

A modal interrupts the user. Every modal should justify the interruption. Most shouldn't exist.

When to use a modal

Use modal	Don't use modal
Confirming a destructive action with no undo	Confirming a reversible action (use Undo toast)
Focused task that requires full attention (image edit, payment)	Editing a field (inline edit)
Error or warning blocking progress	Informational messages (toast/banner)
Critical form that must complete before continuing	Forms that can live on a page
Collecting user input for current flow only	Secondary workflows (new tab/page)

Undo beats confirm. A toast with "Item deleted. [Undo]" is almost always better than "Are you sure?"

Modal vs drawer vs popover vs sheet

Pattern	Overlay	Blocks page	Anchored	Use
Modal dialog	Full	Yes	Center	Critical decisions, focused tasks
Drawer (side)	Partial	Yes	Edge	Settings panels, filters, nav
Popover	None	No	Element	Supplemental info, small forms
Bottom sheet (mobile)	Partial	Yes	Bottom	Mobile primary pattern for drawers
Fullscreen sheet (mobile)	Full	Yes	Full	Complex mobile tasks

Use the <dialog> element

Native <dialog> handles focus trap, ESC, backdrop, and scroll lock for free. Stop reinventing it.

<dialog id="confirm-delete">
  <h2>Delete project?</h2>
  <p>This permanently removes the project and all 47 files.</p>
  <div class="actions">
    <button value="cancel">Cancel</button>
    <button value="confirm" class="destructive">Delete project</button>
  </div>
</dialog>

<script>
  const dialog = document.getElementById('confirm-delete');
  dialog.showModal(); // Modal with backdrop + focus trap
  // dialog.show();  // Non-modal
</script>

If you must build without <dialog>, the requirements below are non-negotiable.

Required behaviors

1. Focus moves into the dialog on open. The first focusable element, or the most useful (e.g., the primary action).
2. Focus trapped inside. Tab and Shift+Tab cycle within. Nothing outside is reachable.
3. Focus returns to trigger on close. The element that opened the modal gets focus back.
4. Escape closes. Unless explicitly forbidden (rare).
5. Click outside closes. For non-critical modals. For critical confirmations, require explicit button press.
6. Scroll locked on body. No scrolling behind the modal. overflow: hidden on <html>, not <body> — that loses scroll position on mobile Safari.
7. Backdrop visible. 40–60% opacity black or tinted dark with blur for modern feel.
8. role="dialog" or role="alertdialog". Alertdialog for critical confirmations.
9. aria-labelledby pointing to the heading. Or aria-label if no visible heading.