modal-and-overlay-patterns

Modal and Overlay Patterns

Overlays appear above the main content layer. They range from lightweight popovers (non-blocking, anchored to a trigger) to full blocking modals (require a user response before the app continues). Choosing the right overlay type for the task prevents unnecessary interruption and keeps the user oriented.

The Overlay Hierarchy

Choose the lightest type that satisfies the task. Heavier overlays carry higher cognitive cost.

Decision rule: If the user can continue using the rest of the app while the overlay is open, use a non-blocking type (drawer, popover). If the app must wait for the user's response, use a modal.

Tooltip

A tooltip appears on hover or keyboard focus and disappears when the trigger loses focus. It is purely informational — no interactive elements inside.

• Content: one short sentence, label, or keyboard shortcut. Never put a link or button inside a tooltip.
• Delay: 300–400ms on hover; no delay on keyboard focus.
• Position: prefer above the trigger; auto-flip when viewport edge is near.
• ARIA: role="tooltip" on the element; aria-describedby on the trigger pointing to the tooltip id.

Popover

A popover is anchored to a trigger but contains interactive content — a colour picker, a date range selector, a small form, a list of filters. Unlike a tooltip, it stays open while the user interacts.

• Max width: 280–360px. For larger content, use a drawer.
• Position: anchored to the trigger; auto-flip to stay in viewport.
• Dismiss: click outside, Escape key, or explicit close button when the content is long.
• Focus: move focus into the popover when it opens; return focus to the trigger on close.
• ARIA: role="dialog" (if interactive) or role="listbox" (if a list); aria-haspopup on the trigger.

Dropdown and Menu

A dropdown lists selectable options or actions anchored to a trigger button. It is the lightest interactive overlay.

• Separate select dropdowns (the user picks one value that persists) from action menus (the user triggers an action that doesn't persist as a value).
• Width: at least as wide as the trigger; cap at 280px.
• Long lists: add a search input at the top when there are more than 8–10 items.
• Keyboard: ↑/↓ to move between items, Enter to select, Escape to close.

Bottom Sheet (Mobile)

On small screens, a bottom sheet replaces modals and popovers. It slides up from the bottom edge and feels native to touch devices.

• Peek height: Show a small portion of the sheet first (a handle + title), let the user drag to expand.
• Full-height: For longer content or forms that need the full viewport.
• Dismiss: swipe down, tap the scrim, or press Escape.
• Do not centre dialogs on mobile — use a bottom sheet instead (centred modals are too small and hard to reach).
• ARIA: treat as role="dialog" with the same focus management as a modal.

Drawer / Side Panel

A drawer slides in from the left or right and partially covers the main content. Use it for secondary editing tasks, detail views, or settings that the user might refer back to while using the main content.

• Right drawer: Detail view, editing form, filter/sort panel. Most common.
• Left drawer: Navigation on mobile (hamburger menu pattern).
• Width: 320–480px on desktop. Full-width on mobile (effectively a bottom sheet or full-screen overlay instead).
• Scrim: a semi-transparent backdrop (rgba(0,0,0,0.4)) behind the drawer dims the main content.
• Dismiss: Escape key, explicit close button. Clicking the scrim is optional — avoid it when the drawer contains an unsaved form.
• Do not use a drawer when the task is blocking (e.g. a required decision). Use a modal instead.
• ARIA: role="dialog", aria-modal="true", aria-labelledby pointing to the drawer title.

Modal / Dialog

A modal blocks the entire UI with a full scrim. Use it only when the app genuinely cannot continue without the user's response.

When to use a modal

• Confirming a destructive or irreversible action
• A required form that must be submitted before continuing
• An error or warning that requires the user's acknowledgement

When not to use a modal

• Displaying information the user can read at their leisure → use an inline notice or notification
• A task the user might want to do alongside the main content → use a drawer
• A large form with many fields → use a dedicated page or a drawer

Anatomy

┌──────────────────────────────────┐
│  Title                      [✕]  │  ← Header: title + close button
├──────────────────────────────────┤
│                                  │
│  Body content                    │  ← Content: scrolls if needed
│  (description, form, media)      │
│                                  │
├──────────────────────────────────┤
│               [Cancel]  [Confirm]│  ← Footer: actions, right-aligned
└──────────────────────────────────┘

Sizing

Content that overflows the modal height should scroll within the body area only — the header and footer must remain visible.

Dismiss behaviour

For destructive or irreversible actions: disable Escape and click-outside dismissal. The user must explicitly press Cancel or Confirm.

Stacking modals

Avoid opening a modal from inside a modal. It signals an information architecture problem — the task is likely too complex for a single dialog.

If a secondary overlay is unavoidable, use a popover anchored inside the modal rather than another full modal. Never stack two blocking scrim overlays.

Focus Management

Every overlay must manage focus correctly. Broken focus management is one of the most common accessibility failures.

On open

1. Move focus to the first interactive element inside the overlay (usually the first field, or the confirm button for confirmations).
2. Trap focus: Tab and Shift+Tab cycle within the overlay only; focus cannot escape to the content behind the scrim.

On close

Return focus to the element that triggered the overlay. If the trigger no longer exists (the element was deleted), move focus to a logical nearby element.

Implementation note

Use a focus trap library or the native <dialog> element, which handles trapping natively in modern browsers. Rolling a manual focus trap is error-prone.

ARIA for Modals and Drawers

<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="modal-title"
  aria-describedby="modal-description"
>
  <h2 id="modal-title">Delete project?</h2>
  <p id="modal-description">
    This will permanently delete "Apollo" and all its data. This cannot be undone.
  </p>
  <button>Cancel</button>
  <button>Delete</button>
</div>

• role="dialog" on the container
• aria-modal="true" tells screen readers to ignore content behind the overlay
• aria-labelledby points to the dialog title's id
• aria-describedby points to the description's id (optional but helpful for confirmations)
• The scrim backdrop should have aria-hidden="true" — screen readers must not read it

Destructive Confirmation Pattern

Confirmation dialogs for destructive actions must name the item and consequence. Generic "Are you sure?" dialogs don't give enough context.

Do:

Delete "Apollo Project"? This will permanently remove all tasks, files, and history. This cannot be undone. [Cancel] [Delete project]

Don't:

Are you sure you want to do this? [No] [Yes]

• The primary destructive action button uses --color-error / --color-danger, not --color-primary.
• Label the destructive button explicitly: "Delete project", "Remove member", "Cancel order" — not just "OK" or "Confirm".
• Cancel is always on the left (or secondary position); destructive action on the right.

Review Checklist

• Is the correct overlay type chosen for the task (tooltip / popover / menu / bottom sheet / drawer / modal)?
• Is a modal avoided when a drawer or inline pattern would suffice?
• Does the modal/drawer have a visible title, body, and clear action buttons?
• Does overflow content scroll within the body — with the header and footer fixed?
• Is Escape disabled for destructive actions (click-outside too)?
• Does focus move into the overlay on open, and return to the trigger on close?
• Is focus trapped within the overlay while it's open?
• Is role="dialog", aria-modal="true", aria-labelledby set correctly?
• Does the destructive confirm dialog name the item and describe the consequence?
• Is the destructive button labelled explicitly (not "OK" or "Confirm")?
• Are stacked modals avoided?
• On mobile, are modals replaced with bottom sheets?