--- productId: material-ui title: React Modal component components: Modal githubLabel: 'scope: modal' waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ githubSource: packages/mui-material/src/Modal --- # Modal The modal component provides a solid foundation for creating dialogs, popovers, lightboxes, or whatever else. The component renders its `children` node in front of a backdrop component. The `Modal` offers important features: - 💄 Manages modal stacking when one-at-a-time just isn't enough. - 🔐 Creates a backdrop, for disabling interaction below the modal. - 🔐 It disables scrolling of the page content while open. - ♿️ It properly manages focus; moving to the modal content, and keeping it there until the modal is closed. - ♿️ Adds the appropriate ARIA roles automatically. {{"component": "@mui/internal-core-docs/ComponentLinkHeader", "design": false}} :::info The term "modal" is sometimes used to mean "dialog", but this is a misnomer. A modal window describes parts of a UI. An element is considered modal if [it blocks interaction with the rest of the application](https://en.wikipedia.org/wiki/Modal_window). ::: If you are creating a modal dialog, you probably want to use the [Dialog](/material-ui/react-dialog/) component rather than directly using Modal. Modal is a lower-level construct that is leveraged by the following components: - [Dialog](/material-ui/react-dialog/) - [Drawer](/material-ui/react-drawer/) - [Menu](/material-ui/react-menu/) - [Popover](/material-ui/react-popover/) ## Basic modal ```tsx import * as React from 'react'; import Box from '@mui/material/Box'; import Button from '@mui/material/Button'; import Typography from '@mui/material/Typography'; import Modal from '@mui/material/Modal'; const style = { position: 'absolute', top: '50%', left: '50%', transform: 'translate(-50%, -50%)', width: 400, bgcolor: 'background.paper', border: '2px solid #000', boxShadow: 24, p: 4, }; export default function BasicModal() { const [open, setOpen] = React.useState(false); const handleOpen = () => setOpen(true); const handleClose = () => setOpen(false); return (
Text in a modal Duis mollis, est non commodo luctus, nisi erat porttitor ligula.
); } ``` Notice that you can disable the outline (often blue or gold) with the `outline: 0` CSS property. ## Nested modal Modals can be nested, for example a select within a dialog, but stacking of more than two modals, or any two modals with a backdrop is discouraged. If you need to nest modals, use the `hideBackdrop` prop on nested Modals to avoid stacking multiple backdrops, which can obscure the active modal or affect interactions. ```tsx import * as React from 'react'; import Box from '@mui/material/Box'; import Modal from '@mui/material/Modal'; import Button from '@mui/material/Button'; const style = { position: 'absolute', top: '50%', left: '50%', transform: 'translate(-50%, -50%)', width: 400, bgcolor: 'background.paper', border: '2px solid #000', boxShadow: 24, pt: 2, px: 4, pb: 3, }; function ChildModal() { const [open, setOpen] = React.useState(false); const handleOpen = () => { setOpen(true); }; const handleClose = () => { setOpen(false); }; return (

Text in a child modal

Lorem ipsum, dolor sit amet consectetur adipisicing elit.

); } export default function NestedModal() { const [open, setOpen] = React.useState(false); const handleOpen = () => { setOpen(true); }; const handleClose = () => { setOpen(false); }; return (

Text in a modal

Duis mollis, est non commodo luctus, nisi erat porttitor ligula.

); } ``` ## Transitions The open/close state of the modal can be animated with a transition component. This component should respect the following conditions: - Be a direct child descendent of the modal. - Have an `in` prop. This corresponds to the open/close state. - Call the `onEnter` callback prop when the enter transition starts. - Call the `onExited` callback prop when the exit transition is completed. These two callbacks allow the modal to unmount the child content when closed and fully transitioned. Modal has built-in support for [react-transition-group](https://github.com/reactjs/react-transition-group). ```tsx import * as React from 'react'; import Backdrop from '@mui/material/Backdrop'; import Box from '@mui/material/Box'; import Modal from '@mui/material/Modal'; import Fade from '@mui/material/Fade'; import Button from '@mui/material/Button'; import Typography from '@mui/material/Typography'; const style = { position: 'absolute', top: '50%', left: '50%', transform: 'translate(-50%, -50%)', width: 400, bgcolor: 'background.paper', border: '2px solid #000', boxShadow: 24, p: 4, }; export default function TransitionsModal() { const [open, setOpen] = React.useState(false); const handleOpen = () => setOpen(true); const handleClose = () => setOpen(false); return (
Text in a modal Duis mollis, est non commodo luctus, nisi erat porttitor ligula.
); } ``` Alternatively, you can use [react-spring](https://github.com/pmndrs/react-spring). ```tsx import * as React from 'react'; import Backdrop from '@mui/material/Backdrop'; import Box from '@mui/material/Box'; import Modal from '@mui/material/Modal'; import Button from '@mui/material/Button'; import Typography from '@mui/material/Typography'; import { useSpring, animated } from '@react-spring/web'; interface FadeProps { children: React.ReactElement; in?: boolean; onClick?: any; onEnter?: (node: HTMLElement, isAppearing: boolean) => void; onExited?: (node: HTMLElement, isAppearing: boolean) => void; ownerState?: any; } const Fade = React.forwardRef(function Fade(props, ref) { const { children, in: open, onClick, onEnter, onExited, ownerState, ...other } = props; const style = useSpring({ from: { opacity: 0 }, to: { opacity: open ? 1 : 0 }, onStart: () => { if (open && onEnter) { onEnter(null as any, true); } }, onRest: () => { if (!open && onExited) { onExited(null as any, true); } }, }); return ( {React.cloneElement(children, { onClick })} ); }); const style = { position: 'absolute', top: '50%', left: '50%', transform: 'translate(-50%, -50%)', width: 400, bgcolor: 'background.paper', border: '2px solid #000', boxShadow: 24, p: 4, }; export default function SpringModal() { const [open, setOpen] = React.useState(false); const handleOpen = () => setOpen(true); const handleClose = () => setOpen(false); return (
Text in a modal Duis mollis, est non commodo luctus, nisi erat porttitor ligula.
); } ``` ## Performance The content of modal is unmounted when closed. If you need to make the content available to search engines or render expensive component trees inside your modal while optimizing for interaction responsiveness it might be a good idea to change this default behavior by enabling the `keepMounted` prop: ```jsx ``` ```tsx import * as React from 'react'; import Box from '@mui/material/Box'; import Modal from '@mui/material/Modal'; import Button from '@mui/material/Button'; import Typography from '@mui/material/Typography'; const style = { position: 'absolute', top: '50%', left: '50%', transform: 'translate(-50%, -50%)', width: 400, bgcolor: 'background.paper', border: '2px solid #000', boxShadow: 24, p: 4, }; export default function KeepMountedModal() { const [open, setOpen] = React.useState(false); const handleOpen = () => setOpen(true); const handleClose = () => setOpen(false); return (
Text in a modal Duis mollis, est non commodo luctus, nisi erat porttitor ligula.
); } ``` As with any performance optimization, this is not a silver bullet. Be sure to identify bottlenecks first, and then try out these optimization strategies. ## Server-side modal React [doesn't support](https://github.com/react/react/issues/13097) the [`createPortal()`](https://react.dev/reference/react-dom/createPortal) API on the server. In order to display the modal, you need to disable the portal feature with the `disablePortal` prop: ```tsx import * as React from 'react'; import Modal from '@mui/material/Modal'; import Typography from '@mui/material/Typography'; import Box from '@mui/material/Box'; export default function ServerModal() { const rootRef = React.useRef(null); return ( rootRef.current!} > ({ position: 'relative', width: 400, bgcolor: 'background.paper', border: '2px solid #000', boxShadow: theme.shadows[5], p: 4, })} > Server-side modal If you disable JavaScript, you will still see me. ); } ``` ## Limitations ### Focus trap The modal moves the focus back to the body of the component if the focus tries to escape it. This is done for accessibility purposes. However, it might create issues. In the event the users need to interact with another part of the page, for example with a chatbot window, you can disable the behavior: ```jsx ``` ## Accessibility (WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) - Be sure to add `aria-labelledby="id..."`, referencing the modal title, to the `Modal`. Additionally, you may give a description of your modal with the `aria-describedby="id..."` prop on the `Modal`. ```jsx ``` - The [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/dialog/) can help you set the initial focus on the most relevant element, based on your modal content. - Keep in mind that a "modal window" overlays on either the primary window or another modal window. Windows under a modal are **inert**. That is, users cannot interact with content outside an active modal window. This might create [conflicting behaviors](#focus-trap). # Modal API ## Demos For examples and details on the usage of this React component, visit the component demo pages: - [Modal](https://mui.com/material-ui/react-modal/) ## Import ```jsx import Modal from '@mui/material/Modal'; // or import { Modal } from '@mui/material'; ``` ## Props | Name | Type | Default | Required | Description | |------|------|---------|----------|-------------| | children | `element` | - | Yes | | | open | `bool` | - | Yes | | | classes | `object` | - | No | Override or extend the styles applied to the component. | | closeAfterTransition | `bool` | `false` | No | | | component | `elementType` | - | No | | | container | `HTML element \| func` | - | No | | | disableAutoFocus | `bool` | `false` | No | | | disableEnforceFocus | `bool` | `false` | No | | | disablePortal | `bool` | `false` | No | | | disableRestoreFocus | `bool` | `false` | No | | | disableScrollLock | `bool` | `false` | No | | | hideBackdrop | `bool` | `false` | No | | | keepMounted | `bool` | `false` | No | | | onClose | `function(event: object, reason: string) => void` | - | No | | | onTransitionEnter | `func` | - | No | | | onTransitionExited | `func` | - | No | | | slotProps | `{ backdrop?: func \| object, root?: func \| object }` | `{}` | No | | | slots | `{ backdrop?: elementType, root?: elementType }` | `{}` | No | | | sx | `Array \| func \| object` | - | No | The system prop that allows defining system overrides as well as additional CSS styles. | > **Note**: The `ref` is forwarded to the root element (HTMLDivElement). > Any other props supplied will be provided to the root element (native element). ## Slots | Name | Default | Class | Description | |------|---------|-------|-------------| | root | `'div'` | `.MuiModal-root` | The component that renders the root. | | backdrop | `undefined` | `.MuiModal-backdrop` | The component that renders the backdrop. | ## CSS ### Rule name | Global class | Rule name | Description | |--------------|-----------|-------------| | - | hidden | Class name applied to the root element if the `Modal` has exited. | ## Source code If you did not find the information on this page, consider having a look at the implementation of the component for more detail. - [/packages/mui-material/src/Modal/Modal.js](https://github.com/mui/material-ui/tree/HEAD/packages/mui-material/src/Modal/Modal.js)