Modal component

Playground

Change a prop on the right and the preview updates. Switch to Code to copy what you see.

Recipes

Copy-paste patterns for the ways Modal actually gets used — each one a real, self-contained example.

const [isOpen, setIsOpen] = useState(false);

<Button onPress={() => setIsOpen(true)}>Open</Button>
<Modal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="Publish changes"
  actions={
    <>
      <Button variant="soft" onPress={() => setIsOpen(false)}>Cancel</Button>
      <Button color="primary" onPress={() => setIsOpen(false)}>Publish</Button>
    </>
  }
>
  Your changes will go live immediately.
</Modal>

<Modal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  role="alertdialog"
  title="Delete project"
  actions={
    <>
      <Button variant="soft" onPress={() => setIsOpen(false)}>Cancel</Button>
      <Button color="danger" onPress={handleDelete}>Delete</Button>
    </>
  }
>
  This can't be undone. All data will be permanently removed.
</Modal>

<Modal isOpen={isOpen} onClose={onClose} size="sm" title="Small">…</Modal>
<Modal isOpen={isOpen} onClose={onClose} size="lg" title="Large">…</Modal>
<Modal isOpen={isOpen} onClose={onClose} size="full" title="Full screen">…</Modal>

<Modal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  closeOnOutsideClick={false}
  title="Complete setup"
>
  Finish these steps before closing.
</Modal>

Controlled open state

isOpen and onClose are both required — Modal never manages its own visibility. onClose fires from every dismissal path (backdrop click, Escape, the header's close button) so there's exactly one place to update your state, regardless of how the user closed it.

const DeleteConfirm = () => {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <>
      <Button color="danger" onPress={() => setIsOpen(true)}>Delete item</Button>
      <Modal
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        title="Delete item"
        actions={
          <>
            <Button variant="soft" onPress={() => setIsOpen(false)}>Cancel</Button>
            <Button color="danger" onPress={handleDelete}>Delete</Button>
          </>
        }
      >
        This can't be undone. Are you sure?
      </Modal>
    </>
  );
};

Header, body, footer

title renders the header (built on PageTitle internally, with a close button next to it unless dismissible={false}), children is the body, and actions is the footer — typically Cancel/Confirm-style buttons. All three are optional independently, so a Modal can be body-only, or header+body with no footer.

Safe stacking

Opening a second Modal (or a Drawer, since they share the same overlay stack) while one is already open works correctly out of the box — z-index and backdrop layering are computed automatically, and Escape only ever closes the topmost overlay, not every open one at once.

// Nested confirm-inside-a-modal -- stacks correctly without manual z-index math
<Modal isOpen={editOpen} onClose={() => setEditOpen(false)} title="Edit profile">
  <ProfileForm />
  <Modal
    isOpen={confirmDiscard}
    onClose={() => setConfirmDiscard(false)}
    title="Discard changes?"
    role="alertdialog"
  >
    Unsaved changes will be lost.
  </Modal>
</Modal>

Sizing and animation

size accepts the usual token scale plus "full" for an edge-to-edge modal, or a raw string/number for an exact width. animationType controls how it enters/exits (fade, zoom, or a directional slide) with animationDuration/easing to fine-tune the feel; blur and backgroundOpacity control the backdrop underneath it.

<Modal isOpen={isOpen} onClose={onClose} size="lg" animationType="slideUp" title="Details">
  {content}
</Modal>

Confirmation dialogs: role="alertdialog"

For a modal whose sole purpose is a decision the user must make (not just informational content), set role="alertdialog" instead of the default "dialog" — screen readers announce it more assertively, matching the native alertdialog semantics.

Props

The full public API for Modal. Every prop is stable and intentionally typed.

Accessibility

• •Traps focus inside the modal while open, and restores focus to whatever triggered it on close — a keyboard user never gets dropped behind the modal into the rest of the page.
• •closeOnEscape (on by default) closes the modal on Escape; when overlays are stacked, Escape only ever closes the topmost one.
• •initialFocusRef lets you send initial focus somewhere other than the default (the modal itself, or its first focusable element) — useful when a specific field should be focused immediately, like a text input in a form modal.
• •The header's close button has an accessible name via closeLabel (defaults to "Close modal") — override it if the default doesn't read naturally for a specific modal's content.

Best practices

• ◆Use role="alertdialog" for confirmations and destructive actions, and leave the default role="dialog" for general content modals.
• ◆Set closeOnOutsideClick={false} for a modal representing a multi-step or destructive flow the user shouldn't be able to dismiss by an accidental click outside it.
• ◆Keep actions to one or two buttons — a modal footer with many actions usually means the content itself should be a full page instead.
• ◆For content that slides in from an edge rather than appearing centered (a filters panel, a details sidebar), reach for Drawer instead — it shares Modal's focus-trapping and stacking behavior.
• ◆Don't nest more than two modals deep in practice, even though stacking is supported — each additional layer makes it harder for the user to track their way back out.