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.mdpackages/gamut/agent-tools/skills/gamut-modal/SKILL.md
GitHubGamut 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:
- Mount gating —
OverlayreturnsnullwhenisOpenis falsy. There's no unmount transition; if you need an exit animation, animate your own trigger, not the Modal. - Portal — content renders into
BodyPortal(aReactDOM.createPortaltodocument.body), not inline where<Modal>is declared. This is why a Modal reliably renders above in-page content regardless of surroundingoverflow/position— but it also means a second portal (a non-inlinePopoverContainer,SelectDropdownmenu, orDatePickercalendar) opened from inside the Modal is a separate sibling portal, not a descendant of the Modal's — seegamut-z-indexfor why that can render behind the Modal. - Focus trap —
FocusTrap(react-focus-on→focus-lock) wrapsModalContainerand constrains Tab/Shift+Tab to elements inside it whileactive(mirrorsOverlay'sinline— always active for Modal/Dialog since they're neverinline). - Initial focus —
ModalContainercarriesdata-autofocusandtabIndex={-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.containerFocusRefgives 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. - Dismiss paths — Escape (
escapeCloses, defaulttrue), click on the shroud outsideModalContainer(clickOutsideCloses, defaulttrue), and the built-in closeIconButton(suppress withcloseButtonProps.hidden) all callonRequestClose.Dialog'sconfirmCta/cancelCtacallonRequestClosefirst, then their ownonClick. - Return focus —
react-focus-onreturns focus to whatever triggered the Modal when it unmounts (defaultreturnFocusbehavior) — 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>