Modal

import { Modal } from "@knitui/components";

Usage

Modal is always controlled: pass opened and an onClose that flips it back. Nothing opens a modal implicitly, so there is never a hidden source of truth for whether it is on screen.

import { Button, Modal } from "@knitui/components";
import { useDisclosure } from "@knitui/hooks";

function DeleteAccount() {
  const [opened, { open, close }] = useDisclosure(false);

  return (
    <>
      <Button onPress={open}>Delete account</Button>

      <Modal opened={opened} onClose={close} title="Delete account?">
        This cannot be undone.
      </Modal>
    </>
  );
}

useDisclosure is the usual companion — it is the opened / open / close / toggle tuple this pattern always needs.

For more structure, compose the parts directly: Modal.Header, Modal.Title, Modal.Body, Modal.CloseButton. The body scrolls on its own when the content is taller than the viewport, so the header stays pinned; withHeaderDivider draws a rule between them once the body has scrolled.

size sets the panel width, centered centres it vertically, and fullScreen expands it to fill the viewport — useful as a responsive escape hatch on phones.

When to use something else

• A panel sliding in from an edge → Drawer
• A sheet the user drags up from the bottom on native → Sheet
• A small transient layer anchored to a trigger → Popover

Examples

Props

Style slots

Every part of Modal can be styled through the styles prop. Explicit props on the component always win over slot styles.

Plus 493 inherited style props from Box — the full Tamagui/React Native style surface, including token shorthands like p, mx, bg and c. See Tokens for the scales they accept, or the full list.

Accessibility

The panel renders with role="dialog" and aria-modal, so assistive technology treats the rest of the page as inert while it is open.

Naming happens automatically when you pass title — it renders into the header and becomes the dialog's aria-labelledby target. If you build a custom header instead, supply aria-labelledby (pointing at your own heading) or aria-label yourself; a dialog with no accessible name is announced only as "dialog".

Three defaults do the work, and all three are on unless you turn them off:

• trapFocus keeps Tab inside the panel, via the shared useFocusTrap hook.
• returnFocus moves focus back to whatever opened the modal when it closes, so the keyboard user is not dropped at the top of the document.
• lockScroll stops the page behind the scrim from scrolling.

closeOnClickOutside is also on by default. Turn it off for a destructive confirmation, where an accidental click outside should not dismiss the question.