Modal – Once UI

The Modal component creates a full-screen overlay with a slide-up animation from the bottom. It features automatic scroll locking, keyboard navigation, and click-outside-to-close functionality.

Prefer Dialog for dialogs

For confirmations, forms and other dialogs, use Dialog: it adds a description, a footer for actions, stacking over a base dialog, and closeOnClickaway. For a panel from an edge, use Drawer. Modal stays for a full-height sheet with its own backdrop, which neither covers yet; 3.0 plans to fold it into Dialog.

Modal

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

return (
<>
  <Button onClick={() => setIsOpen(true)}>
    Open Modal
  </Button>
  <Modal
    open={isOpen}
    onClose={() => setIsOpen(false)}
    title="Modal Title"
  >
    <Column fillWidth gap="16" marginTop="12">
      <Text>
        Modal content goes here. This area can contain any React components.
      </Text>
      <Input id="example" label="Example input" />
    </Column>
  </Modal>
</>
);

With Backdrop

Add custom backdrop content behind the modal dialog using the backdrop prop.

With Backdrop

<Modal
open={isOpen}
onClose={() => setIsOpen(false)}
title="Modal with Backdrop"
backdrop={
  <BlobFx position="absolute" fill seed={42} />
}
>
<Text>
  The backdrop appears behind the modal content.
</Text>
</Modal>

Features

The Modal component includes several built-in features:

Smooth animations: Fade-in overlay with slide-up modal transition
Scroll lock: Prevents body scrolling while modal is open
Keyboard navigation: Press Escape to close
Click outside: Click outside the modal to dismiss
Auto-scroll reset: Content scrolls to top when modal opens
Accessibility: role="dialog" and aria-modal="true" on the overlay

Focus is not trapped

Modal does not currently contain focus: Tab from the last control inside it moves to the page behind, and focus is not returned to the trigger on close. aria-modal="true" tells a screen reader the rest of the page is inert, which is not yet enforced.

Until that is fixed, wrap the contents in a FocusTrap when the modal is a real modal step rather than an aside — or use Dialog, which traps focus and restores it.

Workaround

<Modal open={open} onClose={close} title="Rename project">
<FocusTrap active={open} style={{ display: "contents" }}>
  {children}
</FocusTrap>
</Modal>

Behavior

Modal slides up from the bottom with a 600ms ease transition
Overlay fades in with a 300ms transition
Close button is positioned in the top-right corner
Content area is scrollable if it exceeds viewport height
Modal is rendered in a portal to document.body

API reference

	Type	Default
children Modal content	React.ReactNode	—
backdrop Optional backdrop content behind the modal	React.ReactNode	—
titlerequired Modal title displayed at the top	React.ReactNode	—
openrequired Controls modal visibility	boolean	—
onCloserequired Callback when modal should close	() => void	—