/modal-and-overlay-patterns

name: modal-and-overlay-patterns
description: Modals, drawers, bottom sheets and popovers, each with its scope and blocking level. Use when designing dialogs, confirmations, side panels or action sheets.
metadata:
  priority: 7
  pathPatterns:
    - "components/**"
    - "src/components/**"
    - "**/*.tsx"
    - "**/*.jsx"
    - "design-system/**"
    - "ui/**"
  promptSignals:
    phrases:
      - "modal"
      - "dialog"
      - "drawer"
      - "overlay"
      - "popover"
      - "bottom sheet"
      - "sheet"
      - "action sheet"
      - "side panel"
      - "lightbox"
      - "image zoom"
      - "media viewer"
      - "confirm"
      - "confirmation dialog"
retrieval:
  aliases:
    - modal dialog
    - overlay pattern
    - drawer panel
    - bottom sheet
    - popover
    - confirmation dialog
    - side panel
    - action sheet
  intents:
    - design a modal dialog
    - add a confirmation prompt
    - build a side drawer
    - choose between modal and drawer
    - design a bottom sheet for mobile
    - add a popover for contextual info
    - design an image lightbox with zoom
  examples:
    - add a confirm dialog before deleting
    - should this be a modal or a drawer
    - design a side panel for editing details
    - add a popover to explain this field

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.

| Type | Blocks background | Anchored to trigger | Typical content | Dismiss with | |---|---|---|---|---| | **Tooltip** | No | Yes | 1–2 lines of explanatory text | Cursor leave / focus out | | **Popover** | No | Yes | Short interactive content: a form field, a picker, a small list | Click outside, Escape, explicit close | | **Dropdown / Menu** | No | Yes | List of actions or options | Click outside, Escape, selection | | **Bottom sheet** (mobile) | Partial (dimmed) | No | Actions or content on small screens | Swipe down, tap scrim, Escape | | **Drawer / Side panel** | Partial (dimmed) | No | Secondary editing, detail views, long forms | Escape, explicit close; optionally click scrim | | **Dialog / Modal** | Yes (full scrim) | No | Blocking task: confirm action, fill required form | Escape (non-destructive only), explicit button | | **Full-screen overlay** | Yes (complete) | No | Immersive task: media viewer, complex configuration | Explicit close only |

**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.

---

One Shell for the Whole Family

Tooltip, popover, drawer, bottom sheet and dialog are one family, not five components. They share a single shell: the same raised surface, one hairline border, one corner radius, and a shadow that grows with modality. The ones that carry a header and footer share what sits inside: a title that names the object, a hairline under the header, and one footer order used everywhere. Only size, anchoring (arrow or centred) and blocking change between them.

When each overlay is styled on its own, the user meets several dialects of the same message: different radii, button orders and confirm labels. Each one costs a moment of re-learning and makes a destructive confirm easier to misread. One shell is also one code primitive and one design-tool family, so a fix lands everywhere.

**Audit before adding.** List every floating surface in the product and the tokens it uses. Extract the shell into one primitive and build each overlay type on it. The usual find is a confirm popover and a dialog that disagree on footer order, or a dialog header still carrying a heavy rule the rest of the UI has dropped.

---

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