mirror of
https://github.com/nextui-org/nextui.git
synced 2025-12-08 19:26:11 +00:00
179 lines
10 KiB
Plaintext
179 lines
10 KiB
Plaintext
---
|
||
title: "Modal"
|
||
description: "Display a dialog with a custom content that requires attention or provides additional information."
|
||
url: https://nextui.org/docs/components/modal
|
||
---
|
||
|
||
# Modal
|
||
|
||
Displays a dialog with a custom content that requires attention or provides additional information.
|
||
|
||
<ComponentLinks component="modal" reactAriaHook="useModal" />
|
||
|
||
---
|
||
|
||
## 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.
|
||
|
||
<ImportTabs
|
||
commands={{
|
||
main: 'import {Modal, ModalContent, ModalHeader, ModalBody, ModalFooter} from "@nextui-org/react";',
|
||
individual:
|
||
'import {Modal, ModalContent, ModalHeader, ModalBody, ModalFooter} from "@nextui-org/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.
|
||
|
||
<CodeDemo title="Usage" files={modalContent.usage} />
|
||
|
||
### Sizes
|
||
|
||
<CodeDemo title="Sizes" files={modalContent.sizes} />
|
||
|
||
### Non-dissmissable
|
||
|
||
By default the modal can be closed by clicking on the overlay or pressing the <Kbd>Esc</Kbd> key.
|
||
You can disable this behavior by setting the `isDismissable` prop to `false`.
|
||
|
||
<CodeDemo title="Non-dissmissible" files={modalContent.nonDismissable} />
|
||
|
||
### Modal position
|
||
|
||
By default the modal is centered on the screen when the breakpoint is greater than `md` and is displayed at the top of the
|
||
screen when the breakpoint is less than `md`. You can change the position of the modal by modifying the `wrapper` slot.
|
||
|
||
<CodeDemo title="Modal position" files={modalContent.position} highlightedLines="12" />
|
||
|
||
### 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.
|
||
|
||
<CodeDemo title="Overflow scroll" files={modalContent.overflow} />
|
||
|
||
### 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.
|
||
|
||
<CodeDemo title="With Form" files={modalContent.form} />
|
||
|
||
> **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 `transparent`.
|
||
|
||
<CodeDemo title="Backdrop" files={modalContent.backdrop} />
|
||
|
||
### Custom Backdrop
|
||
|
||
You can customize the backdrop by using the `backdrop` slot.
|
||
|
||
<CodeDemo title="Custom Backdrop" files={modalContent.customBackdrop} />
|
||
|
||
### Custom Motion
|
||
|
||
Modal offers a `motionProps` property to customize the `enter` / `exit` animation.
|
||
|
||
<CodeDemo title="Custom Motion" highlightedLines="14-31" files={modalContent.customMotion} />
|
||
|
||
> Learn more about Framer motion variants [here](https://www.framer.com/motion/animation/#variants).
|
||
|
||
## 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.
|
||
|
||
<CodeDemo title="Custom Styles" highlightedLines="15-20" files={modalContent.customStyles} />
|
||
|
||
<Spacer y={4} />
|
||
|
||
## Data Attributes
|
||
|
||
`Modal` has the following attributes on the `root` element:
|
||
|
||
- **data-open**:
|
||
When the modal is open. Based on modal state.
|
||
- **data-dismissable**:
|
||
When the modal is dismissable. Based on `isDismissable` prop.
|
||
|
||
<Spacer y={4} />
|
||
|
||
## Accessibility
|
||
|
||
- Content outside the modal is hidden from assistive technologies while it is open.
|
||
- The modal optionally closes when interacting outside, or pressing the <kbd>Esc</kbd> 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.
|
||
|
||
<Spacer y={4} />
|
||
|
||
## API
|
||
|
||
### Modal Props
|
||
|
||
| Attribute | Type | Description | Default |
|
||
| ------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------- |
|
||
| children\* | `ReactNode` | The content of the modal. It's usually the `ModalContent`. | - |
|
||
| size | `xs` \| `sm` \| `md` \| `lg` \| `xl` \| `2xl` \| `3xl` \| `4xl` \| `5xl` \| `full` | The modal size. This changes the modal `max-width` and `height` (full). | `md` |
|
||
| color | `default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger` | The modal color theme. | `default` |
|
||
| radius | `none` \| `base` \| `sm` \| `md` \| `lg` \| `xl` \| `2xl` \| `3xl` | The modal border radius. | `xl` |
|
||
| shadow | `none` \| `xs` \| `sm` \| `md` \| `lg` \| `xl` \| `2xl` \| `inner` | The modal shadow. | `lg` |
|
||
| backdrop | `transparent` \| `opaque` \| `blur` | The modal backdrop type. | `opaque` |
|
||
| scrollBehavior | `normal` \| `inside` \| `outside` | The modal scroll behavior. | `normal` |
|
||
| isOpen | `boolean` | Whether the modal is open by default (controlled). | - |
|
||
| defaultOpen | `boolean` | Whether the modal is open by default (uncontrolled). | - |
|
||
| isDismissable | `boolean` | Whether the modal can be closed by clicking on the overlay or pressing the <Kbd>Esc</Kbd> key. | `true` |
|
||
| isKeyboardDismissDisabled | `boolean` | Whether pressing the <Kbd>Esc</Kbd> key to close the modal should be disabled. | `false` |
|
||
| shouldBlockScroll | `boolean` | Whether the modal should block the scroll of the page on open. | `true` |
|
||
| hideCloseButton | `boolean` | Whether to hide the modal close button. | `false` |
|
||
| closeButton | `ReactNode` | Custom close button to display on top right corner. | - |
|
||
| motionProps | [MotionProps](#motion-props) | The props to modify the framer motion animation. Use the `variants` API to create your own animation. | |
|
||
| portalContainer | `HTMLElement` | The container element in which the overlay portal will be placed. | `document.body` |
|
||
| disableAnimation | `boolean` | Whether the modal should not have animations. | `false` |
|
||
| classNames | `Record<"wrapper"｜ "base"｜ "backdrop"｜ "header" ｜ "body" ｜ "footer" ｜ "closeButton", string>` | Allows to set custom class names for the modal slots. | - |
|
||
|
||
### Modal Events
|
||
|
||
| Attribute | Type | Description |
|
||
| ------------ | --------------------------- | ----------------------------------------------------------- |
|
||
| onOpenChange | `(isOpen: boolean) => void` | Handler that is called when the modal's open state changes. |
|
||
| onClose | `() => void` | Handler that is called when the modal is closed. |
|
||
|
||
<Spacer y={4} />
|
||
|
||
### Modal types
|
||
|
||
#### Motion Props
|
||
|
||
```ts
|
||
export type MotionProps = HTMLMotionProps<"div">; // @see https://www.framer.com/motion/
|
||
```
|