Skip to the content

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).
Overlays

When to use

Use when
  • 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.
Avoid when
  • 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} />

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" (or role="alertdialog") with aria-modal="true", named by title. Without a title, name it with aria-label or aria-labelledby.
  • On open, focus moves to the first interactive element; Tab and Shift+Tab cycle inside; Escape closes; focus returns to the opener.
  • closeLabel names the close button (default 'Fechar'). With noCloseButton, keep an explicit exit in the footer.
  • A Dropdown, Tooltip, Popover or InputDate opened inside the modal renders inside the dialog, above it.

Properties

See also