Modal

Usage

Modal is a controlled component — pair open with a piece of local state and always wire onClose. It handles the portal, body scroll lock, Escape, scrim dismissal (on by default — see closeOnScrimClick), and the role / aria-modal / aria-labelledby (title) or aria-label wiring automatically. Focus is managed by the built-in useFocusTrap hook: on open it lands on the first focusable element inside the panel (the panel itself when there is none), Tab / Shift+Tab wrap inside the panel, and focus is restored to the opener when the dialog closes. Tall content scrolls inside the panel — the body region is the scroll container under an 85vh cap while the header and footer stay put.

import { Modal, Button } from '@epasslive/design-system'

const [open, setOpen] = useState(false)

<Modal
  open={open}
  onClose={() => setOpen(false)}
  title="Confirm refund"
  size="md"
  footer={
    <>
      <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
      <Button variant="danger" onClick={refund}>Confirm refund</Button>
    </>
  }
>
  Refunds are processed within 5–10 business days.
</Modal>

Dismissal and keyboard

Two surfaces close the dialog by default: a click anywhere on the scrim and the Escape key (both call onClose). Scrim dismissal is configurable — pass closeOnScrimClick={false} for destructive or multi-step flows that must be dismissed explicitly; the scrim then renders as a non-interactive, aria-hidden overlay and only your footer actions (and Escape) close the dialog. There is no visible close button — provide your own cancel action in the footer slot. With stacked modals open, a single Escape closes only the topmost layer, so modal-over-modal flows work (one Escape per layer).

Accessible name

Always pass title or ariaLabel so the dialog has an accessible name (WCAG 4.1.2). With a title, the heading is wired to the panel via aria-labelledby; without one, ariaLabel names the dialog directly (aria-label = ariaLabel ?? title). If neither is passed the dialog renders unnamed — avoid that.

Sizing

Four width presets via size: sm (384px), md (448px, default), lg (672px), and full (90vw). The panel is capped at max-h-[85vh] and laid out as a flex column: the title and footer are pinned (shrink-0) while the body region scrolls (overflow-y-auto), so tall content scrolls inside the panel while body scroll is locked.

Dark mode

Modal swaps to ep-surface-elevated with dark slate borders and a tinted backdrop — all tokens have light and dark variants.

Props