Modal

The modal component provides a solid foundation for creating dialogs, popovers, lightboxes, or whatever else.

Introduction

Joy UI provides three modal-related components:

Modal: A container that renders its children node in front of a backdrop component.
ModalClose: A button for closing the modal.
ModalDialog: A component for rendering a modal dialog.

Features

🥞 Manages modal stacking when more than one is needed.
🪟 Automatically creates a backdrop element to disable interaction with the rest of the app.
🔐 Disables page scrolling while open.
⌨️ Manages focus correctly between the modal and its parent app.
♿️ Adds the appropriate ARIA roles automatically.

Component

After installation, you can start building with this component using the following basic elements:

import Modal from '@mui/joy/Modal';

export default function MyApp() {
  return <Modal>{children}</Modal>;
}

Basic usage

The Modal accepts only a single React element as a child. That can be either a Joy UI component, e.g. Sheet, or any other custom element.

Use the Modal Close component to render a close button that inherits the modal's onClose function.

Close reason

The second argument of the onClose gives you the information about how the event is triggered.

The possible values are:

backdropClick: the user clicks on the modal's backdrop.
escapeKeyDown: the user presses Escape on the keyboard.
closeClick: the user clicks on the ModalClose element.

To create a modal dialog, render the Modal Dialog component inside the Modal.

The Dialog will apply spacing to the elements that have aria-labelledby or aria-describedby attribute.

Variant

The Modal Dialog supports the global variants feature.

The Modal Close component's variant adapts automatically to contrast with the Modal Dialog, as demonstrated below:

Size

The Modal Dialog comes in 3 sizes: sm, md (default), and lg.

The Modal Close and Modal Dialog Title components inherit the size from the Modal Dialog unless specified in each component directly.

Layout

The Modal Dialog's layout can be:

center (default): the modal dialog appears at the center of the viewport.
fullScreen: the modal dialog covers the whole viewport.

To add more layout, create a new theme with styleOverrides like this:

const theme = extendTheme({
  components: {
    JoyModalDialog: {
      defaultProps: { layout: 'top' },
      styleOverrides: {
        root: ({ ownerState }) => ({
          ...(ownerState.layout === 'top' && {
            top: '12vh',
            left: '50%',
            transform: 'translateX(-50%)',
          }),
        }),
      },
    },
  },
});

For TypeScript, you need module augmentation to include the new values to the layout prop:

// at the root or theme file
declare module '@mui/joy/ModalDialog' {
  interface ModalDialogPropsLayoutOverrides {
    top: true;
  }
}

Vertical scroll

By default, content within the Modal Dialog won't overflow the screen when its height is bigger than the viewport.

To ensure your content is visible, make the container holding it overflow by adding the overflow CSS property with either scroll or auto values.

The previous section demonstrated how to make content within the modal scrollable.

To make the whole modal scrollable, in case its higher than the viewport, use the Modal Overflow component. It will allow the Modal Dialog to vertically overflow the screen.

The Modal Overflow supports both center and fullScreen built-in layouts.

You can achieve the same result by using the Box component and CSS with the sx prop. However, the Modal Overflow component adds greater convenience:

It makes your styling more consistent, as you won't need to copy styles across different instances.
You can also add theming customization to it directly from the theme.
It automatically handles the close action when the user clicks on the Modal's backdrop.

Alert dialog

Use role="alertdialog" to create an alert dialog that interrupts the user's workflow.

Nested modals

The modal components can be nested:

Transition

The modal components do not come with built-in transitions.

Here is one example using react-transition-group to create a fade animation:

Performance

The modal's content is unmounted when it is not open. This means that it will need to be re-mounted each time it is opened.

If you are rendering "expensive" component trees inside your modal, and you want to optimize for interaction responsiveness, change the default behavior by enabling the keepMounted prop.

Use the keepMounted prop to make the content of the modal available to search engines (even when the modal is closed).

The following demo shows how to apply this prop to keep the modal mounted:

As with any performance optimization, the keepMounted prop won't necessarily solve all of your problems. Explore other possible bottlenecks in performance where you could make more considerable improvements before implementing this prop.

React doesn't support the createPortal() API on the server. Therefore, in order to display a modal rendered on the server, disable the portal feature with the disablePortal prop, as shown in the following demo:

Common examples

Use sx prop with theme.breakpoints.only('xs') to customize the styles of the modal dialog to stick at the bottom in mobile viewport.

Limitations

Focus trap

Base UI Modal moves the focus back to the body of the component if the focus tries to escape it.

This is done for accessibility purposes, but it can potentially create issues for your users.

If the user needs to interact with another part of the page－for example, to interact with a chatbot window while a modal is open in the parent app－you can disable the default behavior with the disableEnforceFocus prop.

Accessibility

See the WAI-ARIA guide on the Dialog (Modal) pattern for complete details on accessibility best practices. Here are a couple of highlights:

All interactive elements must have an accessible name. Use the aria-labelledby="id..." to give your Modal component an accessible name. You can also use aria-describedby="id..." to provide a description of the Modal:
```
<Modal aria-labelledby="modal-title" aria-describedby="modal-description">
  <h2 id="modal-title">My Title</h2>
  <p id="modal-description">My Description</p>
</Modal>
```
Follow the WAI-ARIA authoring practices to help you set the initial focus on the most relevant element based on the content of the modal.

A modal window can sit on top of either the parent application, or another modal window. All windows under the topmost modal are inert, meaning the user cannot interact with them. This can lead to conflicting behaviors.

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.