/modal-and-overlay-patterns

name: modal-and-overlay-patterns
description: Overlays — modals, drawers, bottom sheets, popovers — interrupt or augment the main flow. Each type has a different scope, blocking level, and appropriate use case. Use when designing dialogs, confirmation prompts, side panels, action sheets, or any UI element that appears above the main content layer.
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"
      - "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
  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.

---

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 whe