gamut-modal

Use this skill when implementing or auditing `Modal` or `Dialog` — single vs. multi-view composition, size/layout, close button wiring, and how dismiss (Escape/outside-click) and focus-trap/autofocus

SKILL.md

GitHub

Gamut Modal

Modal and Dialog are the two dialog surfaces in Gamut. Both are thin wrappers around the same Overlay → FocusTrap → ModalContainer stack — Dialog is Modal pre-configured for a single confirm/cancel action.

Source: packages/gamut/src/Modals/Modal.tsx · Dialog.tsx · elements.tsx · types.ts · packages/gamut/src/Overlay/index.tsx · packages/gamut/src/FocusTrap/index.tsx

See also: gamut-accessibility — universal ARIA/focus rules and the shorter Dialog/Modal summary. gamut-z-index — stacking order when something floats above or inside an open Modal.

Storybook: Molecules / Modals / Modal · Molecules / Modals / Dialog


Modal vs Dialog — when to use which

Use Component
Single yes/no or confirm/cancel action (delete, discard, leave page) Dialog
Free-form content, a multi-step wizard (views), or no default action buttons at all Modal

Dialog always renders layout="dialog" (title + content + cancel/confirm row) and always requires confirmCta. Modal defaults to layout="standard" (title + content, no buttons) unless you pass views, which switches it to layout="dialog" automatically.


Props — Modal

Two variants of ModalProps, distinguished by whether views is passed:

Prop Type Default Notes
isOpen boolean — Required in practice — Overlay renders null when falsy. Controls mount/unmount; there is no exit animation.
onRequestClose () => void — Required. Called by Escape, outside-click, and the built-in close button. Must actually flip isOpen — the component never closes itself.
title ReactNode — Renders as headingLevel inside the dialog and feeds the accessible name (see caveat below).
aria-label string — Pass this when title is not a plain string, or there is no visible title.
headingLevel 'h1' | 'h2' 'h2' Use h1 only when the Modal effectively takes over the page.
size 'small' | 'medium' | 'large' | 'fluid' 'fluid' fluid sizes to content; the others are fixed widths (400/540/680px).
scrollable boolean false Enables overflow-y: auto on the content area instead of letting the dialog grow.
closeButtonProps { hidden?, ref?, tip?, tipAlignment?, disabled? } — tip defaults to "Close modal". Set hidden: true only if you supply your own close control in children.
containerFocusRef Ref<HTMLDivElement> — Ref to the dialog's outer container — see Focus management below. Does not change what receives initial focus.
image ReactNode — Rendered above content via ImageContainer, sized to match size.
views ModalViewProps[] — Switches to multi-view wizard mode — see below. Mutually exclusive with children/image at the top level.
clickOutsideCloses boolean true Passed through to Overlay.
escapeCloses boolean true Passed through to Overlay.
shroud boolean true Modal always passes shroud to Overlay; darkens the backdrop.
zIndex number 3 Passed through to Overlay → BodyPortal. See gamut-z-index before overriding.

Props — Dialog

Same overlay/focus mechanics as Modal, with a fixed single-action layout:

Prop Type Notes
title ReactNode Required.
confirmCta { children, href?, onClick? } Required. Rendered as FillButton; onRequestClose fires before its onClick.
cancelCta { children, href?, onClick? } Optional TextButton; same close-then-callback order as confirmCta.
variant Extract<FillButton['variant'], 'primary' | 'danger'> Styles confirmCta; use 'danger' for destructive confirmations.
size 'small' | 'medium' | 'large' Default 'small'. No 'fluid' — Dialog is always a fixed size.
<Dialog
  title="Delete this project?"
  variant="danger"
  confirmCta={{ children: 'Delete', onClick: handleDelete }}
  cancelCta={{ children: 'Cancel' }}
  isOpen={isOpen}
  onRequestClose={() => setIsOpen(false)}
/>

Multi-view Modal (wizard)

Pass views: ModalViewProps[] instead of children. Each view gets its own title/children/image, plus a primaryCta/secondaryCta pair keyed by actionType:

actionType (primary) Behavior
'next' Advances currentView; auto-disables on the last view.
'confirm' Terminal action; variant restricted to 'primary' | 'danger'.
actionType (secondary) Behavior
'back' Retreats currentView; auto-disables on the first view.
'cancel' Calls onRequestClose.
<Modal
  isOpen={isOpen}
  onRequestClose={() => setIsOpen(false)}
  views={[
    {
      title: 'Step 1',
      children: <StepOne />,
      primaryCta: { actionType: 'next', children: 'Next' },
      secondaryCta: { actionType: 'cancel', children: 'Cancel' },
    },
    {
      title: 'Step 2',
      children: <StepTwo />,
      primaryCta: {
        actionType: 'confirm',
        children: 'Finish',
        onClick: handleFinish,
      },
      secondaryCta: { actionType: 'back', children: 'Back' },
    },
  ]}
/>

View-level headingLevel and onRequestClose are not supported per-view — they apply to the whole Modal.


Dismiss and focus-trap — how it actually works

Modal/Dialog render <Overlay shroud onRequestClose={...}> around ModalContainer. Nothing here is bespoke to Modal — it's the same stack every Gamut overlay uses:

  1. Mount gating — Overlay returns null when isOpen is falsy. There's no unmount transition; if you need an exit animation, animate your own trigger, not the Modal.
  2. Portal — content renders into BodyPortal (a ReactDOM.createPortal to document.body), not inline where <Modal> is declared. This is why a Modal reliably renders above in-page content regardless of surrounding overflow/position — but it also means a second portal (a non-inline PopoverContainer, SelectDropdown menu, or DatePicker calendar) opened from inside the Modal is a separate sibling portal, not a descendant of the Modal's — see gamut-z-index for why that can render behind the Modal.
  3. Focus trap — FocusTrap (react-focus-on → focus-lock) wraps ModalContainer and constrains Tab/Shift+Tab to elements inside it while active (mirrors Overlay's inline — always active for Modal/Dialog since they're never inline).
  4. Initial focus — ModalContainer carries data-autofocus and tabIndex={-1}. focus-lock's autofocus engine reads that attribute and focuses the container element itself (not the first focusable child) as soon as the trap activates — this is why the dialog's role and label get announced immediately instead of jumping straight to, say, the close button. containerFocusRef gives you a ref to that same node for later imperative .focus() calls (e.g. re-focusing after an in-modal validation error) — passing it does not change what receives focus on open.
  5. Dismiss paths — Escape (escapeCloses, default true), click on the shroud outside ModalContainer (clickOutsideCloses, default true), and the built-in close IconButton (suppress with closeButtonProps.hidden) all call onRequestClose. Dialog's confirmCta/cancelCta call onRequestClose first, then their own onClick.
  6. Return focus — react-focus-on returns focus to whatever triggered the Modal when it unmounts (default returnFocus behavior) — you don't need to store/restore the trigger ref yourself.
// wrong — Modal can't close itself; nothing flips isOpen
<Modal isOpen={isOpen} onRequestClose={() => {}} title="Confirm" />;

// correct
const [isOpen, setIsOpen] = useState(false);
<Modal isOpen={isOpen} onRequestClose={() => setIsOpen(false)} title="Confirm">
  ...
</Modal>;

Caveat — aria-labelledby uses the title text directly

Modal/Dialog set aria-labelledby={String(title)} rather than pointing at an element id. This works fine for a plain string title, but stringifying a non-text ReactNode title (icons, nested markup) will not produce a useful accessible name. Pass an explicit aria-label on Modal whenever title isn't plain text (Dialog's title has no such escape hatch — keep it plain text).


Stacking order — floating content inside a Modal

Overlay's portal (what Modal/Dialog render into) defaults to zIndex={3}. That default is only safe for what's outside the Modal (it reliably clears a sticky global header, for example) — it says nothing about floating content you put inside the Modal's own children/views.

Concretely: if content inside a Modal opens a second, non-inline portal — a portalling SelectDropdown menu, a non-inline PopoverContainer/Menu, or a DatePicker calendar that isn't inline — that creates a brand-new sibling BodyPortal (default zIndex={1}) next to the Modal's own portal (zIndex={3}). Because 1 < 3, the thing you just opened from inside the Modal can render behind it.

// risky — if SelectDropdown's menu portals, it can render behind this Modal
<Modal isOpen={isOpen} onRequestClose={onClose} title="Edit">
  <SelectDropdown options={options} />
</Modal>

// safer — keep nested floating UI inline, inside the Modal's own stacking context
<Modal isOpen={isOpen} onRequestClose={onClose} title="Actions">
  <PopoverContainer inline isOpen={menuOpen} targetRef={triggerRef}>
    <Menu role="menu">
      <MenuItem onClick={handleAction}>Action</MenuItem>
    </Menu>
  </PopoverContainer>
</Modal>

Full component-by-component z-index reference, the AppWrapper/BodyPortal stacking-tier explanation, and when it's actually safe to add a new value: gamut-z-index.


Basic usage — single-view Modal

<Modal
  isOpen={isOpen}
  onRequestClose={() => setIsOpen(false)}
  title="Notification settings"
  size="medium"
>
  <FormGroup htmlFor="email-opt-in" label="Email me updates">
    <Toggle id="email-opt-in" />
  </FormGroup>
</Modal>