Modal
Modal is a centered dialog that blocks the page — and locks its scroll — until the user confirms, cancels or
closes it. Open it from a trigger (uncontrolled) or own the state with isOpen + onDismiss (controlled).When to use
- A destructive action needs confirmation (delete, overwrite).
- A short flow needs full attention (accept terms, sign in).
- You inspect or edit one item without leaving the list behind it.
- The message is transient — use
Notification. - The content is a hint anchored to an element — use
Popover. - The flow is mobile-first or slides from an edge — use
Sheet.
Usage
<Modal trigger={<Button text="Open modal" />} title="Simple modal">
<Text text="Lorem ipsum dolor sit amet." />
</Modal>trigger is an element (it receives an onClick that toggles the modal) or a render function
({ isOpen, open }) => node. A long body scrolls inside the dialog; the dialog never grows past 84svh.
Controlled
Own the state when something other than a click opens the modal. Pass both isOpen and onDismiss: the overlay,
the close button and Escape call onDismiss. With trigger, both props are ignored (a warning is logged).
import { useToggle } from '@apollion-dsi/core/hooks';
const { active, enable, disable } = useToggle();
<>
<Button onClick={enable} text="Show modal" />
<Modal isOpen={active} onDismiss={disable} title="Modal title" tagline="Supporting text.">
<Text text="Content" />
</Modal>
</>;Variants
variant (primary default, success, warning, danger) colors the header icon and the primary button.
size (small, base default, medium, large) sets the width range.
<Modal variant="danger" size="small" title="Delete file?" primaryAction={({ close }) => close()} {...rest} />Footer
The footer renders when you pass primaryAction or secondaryAction; each button renders only with its own
callback. Both callbacks receive { close }. footer sets the layout: right (default), expanded (buttons at
both ends) or full (primary only, full width). On mobile the buttons stack, primary on top.
<Modal
footer="expanded"
primaryText="Save"
secondaryText="Cancel"
primaryAction={({ close }) => {
save();
close();
}}
secondaryAction={({ close }) => close()}
{...rest}
/>The default labels are 'Confirmar' and 'Cancelar' — set primaryText/secondaryText to localize them.
primaryButton/secondaryButton replace the buttons entirely.
Accessibility
role="dialog"(orrole="alertdialog") witharia-modal="true", named bytitle. Without atitle, name it witharia-labeloraria-labelledby.- On open, focus moves to the first interactive element;
TabandShift+Tabcycle inside;Escapecloses; focus returns to the opener. closeLabelnames the close button (default'Fechar'). WithnoCloseButton, keep an explicit exit in the footer.- A
Dropdown,Tooltip,PopoverorInputDateopened inside the modal renders inside the dialog, above it.
Properties
aria-labelstringnonearia-labelledbystringnonechildrenReactNodenonecloseLabelstringFechardefaultOpenbooleannonefooter"expanded""right""full"'right'iconReactNodenoneisOpenbooleannonenoCloseButtonbooleanfalseonDismiss(() => void)noneonModalOpen(() => void)noneprimaryAction((props: { close: () => void; }) => void)noneprimaryButtonReactNodenoneprimaryTextstring'Confirmar'roleAriaRoledialogsecondaryAction((props: { close: () => void; }) => void)nonesecondaryButtonReactNode((p: { close: () => void; }) => ReactNode)nonesecondaryTextstring'Cancelar'size"small""base""medium""large"'base'taglinestringnonetitlestringnonetriggerReactNode((props: { isOpen: boolean; open: () => void; }) => ReactNode)nonevariant"primary""success""warning""danger"'primary'