Modal

Purpose

A modal is a focused interruption. Use it when the user must attend to something before they can continue — confirming a destructive action, completing a short form, or reviewing important information. Because it blocks all other interaction and adds a cognitive load, it should be reserved for cases where inline content genuinely cannot do the job.

Use a modal for:

• Holiday enquiry forms triggered from a CTA button
• Cancellation or deletion confirmations
• Terms acceptance required before proceeding
• Image lightboxes (show a destination image at full scale)

Do not use a modal for:

• Complex multi-step journeys (use a dedicated page or wizard instead)
• Informational content the user did not request (marketing modals, cookie banners)
• Navigation — modals do not participate in browser history
• Content that can be shown inline without interrupting the flow

Usage

Choose a Modal over a Popover or Drawer when the content genuinely requires the user's full attention and must block other interaction — a confirmation, a short form, or a lightbox. A Popover is lighter-weight and non-blocking; a Drawer better suits longer or navigation-adjacent content that still benefits from staying anchored to one edge of the screen.

Modals are triggered directly by a user action — a button click or link tap — never automatically on page load or after a timer. They typically appear from a CTA on a card or page (enquiry forms), from a destructive action's confirm step, or from an image thumbnail (lightbox).

Anatomy

Variants

Informational

Title + body text + single close action. Used for showing terms, disclosures, or contextual help the user asked for.

---

Confirmation

Title + body description + two actions (confirm + cancel). Used for destructive or irreversible operations. The primary action should be the danger variant Button.

---

Form modal

Title + form fields + submit + cancel. Used for the holiday enquiry form triggered from destination and offer pages. The submit button is full-width in the footer.

Sizes

Default is md. Match the size to the content — a simple confirmation dialog should not be lg.

States

Closed

When open={false}, the modal renders null — no DOM nodes are created. This avoids hidden content that could be accidentally focussed.

Open

When open={true}:

1. A full-viewport backdrop renders with backdrop-blur-sm
2. The panel renders centred with shadow-xl
3. Body scroll is locked (overflow-hidden on document.body)
4. Focus moves to the first focusable element inside the modal
5. Tab key cycles within the modal (focus trap active)

Submitting

When the user submits a form inside a modal, set the submit Button to loading={true}. The modal stays open during submission. Close it programmatically in the onSuccess callback.

Best practices

Props

Accessibility

Dialog role and ARIA

<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="modal-title"
  aria-describedby="modal-desc"
>
  <h2 id="modal-title">Cancel this booking?</h2>
  <p id="modal-desc">This action cannot be undone.</p>
  ...
</div>

• role="dialog" announces the context to screen readers ("dialog" or "alert dialog")
• aria-modal="true" tells screen readers to hide everything outside the modal
• aria-labelledby points to the title element — screen readers read the title when focus enters the modal
• aria-describedby points to the description — screen readers read it after the title

Focus management

When open becomes true:

1. Focus moves to the first focusable element inside the modal (usually the close button or first form field)
2. Tab key cycles through focusable elements inside the modal — focus cannot escape

When open becomes false:

1. Focus returns to the element that triggered the modal (the button that was clicked)
2. This is handled automatically if you store a ref to the trigger

const triggerRef = useRef(null);

// When modal closes, return focus to trigger
useEffect(() => {
  if (!open && triggerRef.current) {
    triggerRef.current.focus();
  }
}, [open]);

<Button ref={triggerRef} onClick={() => setOpen(true)}>
  Enquire
</Button>

Keyboard interaction

Body scroll lock

When the modal opens, overflow-hidden is applied to document.body to prevent background content from scrolling while the modal is open. This is removed when the modal closes.

Skip-nav consideration

If your page has a skip navigation link, ensure it targets content inside the modal when the modal is open — or that the skip link is not reachable while the modal's focus trap is active.

Related components

• Drawer — a better fit for longer or navigation-adjacent content that should stay anchored to a screen edge instead of centred and blocking.
• Popover — a lighter-weight, non-blocking alternative for short contextual content anchored to a trigger element.