Modal

Displays a dialog with a custom content that requires attention or provides additional information.


Installation

npx nextui-cli@latest add modal
No need to install this package if @nextui-org/react is already installed globally.

Import

NextUI exports 5 modal-related components:

  • Modal: The main component to display a modal.
  • ModalContent: The wrapper of the other modal components.
  • ModalHeader: The header of the modal.
  • ModalBody: The body of the modal.
  • ModalFooter: The footer of the modal.

Usage

When the modal opens:

  • Focus is bounded within the modal and set to the first tabbable element.
  • Content behind a modal dialog is inert, meaning that users cannot interact with it.

Sizes

Non-dissmissable

By default, the modal can be closed by clicking on the overlay or pressing the Esc key. You can disable this behavior by setting the following properties:

  • Set the isDismissable property to false to prevent the modal from closing when clicking on the overlay.
  • Set the isKeyboardDismissDisabled property to true to prevent the modal from closing when pressing the Esc key.

By default the modal is centered on screens higher than sm and is at the bottom of the screen on mobile. This placement is called auto, but you can change it by using the placement prop.

Note: The top-center and bottom-center positions mean that the modal is positioned at the top / bottom of the screen on mobile and at the center of the screen on desktop.

Overflow scroll

You can use the scrollBehavior prop to set the scroll behavior of the modal.

  • inside: The modal content will be scrollable.
  • outside: The modal content will be scrollable and the modal will be fixed.

With Form

The Modal handles the focus within the modal content. It means that you can use the modal with form elements without any problem. the focus returns to the trigger when the modal closes.

Note: You can add the autoFocus prop to the first Input component to focus it when the modal opens.

Backdrop

The Modal component has a backdrop prop to show a backdrop behind the modal. The backdrop can be either transparent, opaque or blur. The default value is opaque.

Custom Backdrop

You can customize the backdrop by using the backdrop slot.

Custom Motion

Modal offers a motionProps property to customize the enter / exit animation.

Learn more about Framer motion variants here.

Slots

  • wrapper: The wrapper slot of the modal. It wraps the base and the backdrop slots.
  • base: The main slot of the modal content.
  • backdrop: The backdrop slot, it is displayed behind the modal.
  • header: The header of the modal, it is displayed at the top of the modal.
  • body: The body of the modal, it is displayed in the middle of the modal.
  • footer: The footer of the modal, it is displayed at the bottom of the modal.
  • closeButton: The close button of the modal.

Custom Styles

You can customize the Modal component by passing custom Tailwind CSS classes to the component slots.

Data Attributes

Modal has the following attributes on the base element:

  • data-open: When the modal is open. Based on modal state.
  • data-dismissable: When the modal is dismissable. Based on isDismissable prop.

Accessibility

  • Content outside the modal is hidden from assistive technologies while it is open.
  • The modal optionally closes when interacting outside, or pressing the Esc key.
  • Focus is moved into the modal on mount, and restored to the trigger element on unmount.
  • While open, focus is contained within the modal, preventing the user from tabbing outside.
  • Scrolling the page behind the modal is prevented while it is open, including in mobile browsers.

API

AttributeTypeDescriptionDefault
children*ReactNodeThe content of the modal. It's usually the ModalContent.-
sizexs | sm | md | lg | xl | 2xl | 3xl | 4xl | 5xl | fullThe modal size. This changes the modal max-width and height (full).md
radiusnone | sm | md | lgThe modal border radius.lg
shadownone | sm | md | lgThe modal shadow.lg
backdroptransparent | opaque | blurThe modal backdrop type.opaque
scrollBehaviornormal | inside | outsideThe modal scroll behavior.normal
placementauto | top | center | bottomThe modal position.auto
isOpenbooleanWhether the modal is open by default (controlled).-
defaultOpenbooleanWhether the modal is open by default (uncontrolled).-
isDismissablebooleanWhether the modal can be closed by clicking on the overlay or pressing the Esc key.true
isKeyboardDismissDisabledbooleanWhether pressing the Esc key to close the modal should be disabled.false
shouldBlockScrollbooleanWhether the modal should block the scroll of the page on open.true
hideCloseButtonbooleanWhether to hide the modal close button.false
closeButtonReactNodeCustom close button to display on top right corner.-
motionPropsMotionPropsThe props to modify the framer motion animation. Use the variants API to create your own animation.
portalContainerHTMLElementThe container element in which the overlay portal will be placed.document.body
disableAnimationbooleanWhether the modal should not have animations.false
classNamesRecord<"wrapper"| "base"| "backdrop"| "header" | "body" | "footer" | "closeButton", string>Allows to set custom class names for the modal slots.-
AttributeTypeDescription
onOpenChange(isOpen: boolean) => voidHandler that is called when the modal's open state changes.
onClose() => voidHandler that is called when the modal is closed.

Motion Props

export type MotionProps = HTMLMotionProps<"div">; // @see https://www.framer.com/motion/