# Modals and dialogs are usable on mobile screens

- **Pattern:** `ab-001932` (`mobile-responsiveness.mobile-ux.mobile-modals`)
- **Severity:** low
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-001932
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-001932)

## Why it matters

A modal with `width: 600px` on a 375px phone renders with its right edge off-screen, clipping the close button and any right-aligned action buttons. If the close mechanism is off-screen, the user has no way to dismiss the modal except reloading. Modals also commonly lack `overflow-y: auto`, so long content gets clipped at the bottom of the viewport with no scroll to reach the submit button. Both failure modes trap users.

## Severity rationale

Low because modals are a minority of screens, but a user trapped in a broken modal has no recovery path short of reloading.

## Remediation

Constrain modal width to `90vw` with a `max-width` for desktop, cap height at `90vh`, and enable `overflow-y: auto` on the content. In shadcn/ui, apply these as classes on `DialogContent`. Audit any modal or dialog components in `src/components/ui/`.

```tsx
<DialogContent className="w-[90vw] max-w-lg max-h-[90vh] overflow-y-auto">
```

## Detection

- **ID:** `mobile-modals`
- **Severity:** `low`
- **What to look for:** Examine modal and dialog components. Check their sizing: fixed pixel widths larger than typical phone viewports (>640px), fixed heights that exceed phone viewport heights, or lack of `overflow-y: auto` on modal content. Check whether modals have a close mechanism that works on touch. Look for modals that position content off-center on mobile due to centering patterns without `max-width: calc(100vw - 2rem)` constraints.
- **Pass criteria:** Count all modal, dialog, and overlay components in the codebase (`<dialog>`, modal library components, elements with `position: fixed` or `position: absolute` covering the viewport). For each, verify 3 requirements: (1) responsive sizing (`max-width: 90vw` or `max-width: calc(100vw - 2rem)` or similar), (2) content scrolls if needed (`overflow-y: auto`), (3) touch-accessible close mechanism (visible close button of at least 44x44px). Report: "X of Y modals meet all 3 mobile requirements."
- **Fail criteria:** At least 1 modal has a fixed width exceeding 640px without a responsive `max-width` constraint, or is positioned such that it extends off-screen on phones below 640px width.
- **Skip (N/A) when:** No modal, dialog, or overlay components detected in the codebase — 0 modals found (no `<dialog>`, no modal libraries, no elements with `position: fixed` or `position: absolute` covering the viewport).
- **Detail on fail:** `"Modal in components/ui/modal.tsx has fixed width of 600px with no max-width constraint — 1 of 3 modals will overflow phone viewports below 640px"`.
- **Remediation:**

  ```css
  .modal {
    width: 90vw;
    max-width: 600px;
    max-height: 90vh;
    overflow-y: auto;
    margin: auto;
  }
  ```

  In Tailwind with shadcn/ui:

  ```tsx
  <DialogContent className="w-[90vw] max-w-lg max-h-[90vh] overflow-y-auto">
  ```

---

Taxons: user-experience

HTML version: https://auditbuffet.com/patterns/ab-001932