Modal

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

The component renders itschildren node in front of a backdrop component.TheModal 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.

If you are creating a modal dialog, you probably want to use theDialog component rather than directly using Modal.Modal is a lower-level construct that is leveraged by the following components:

• Dialog
• Drawer
• Menu
• Popover

Basic modal

Notice that you can disable the outline (often blue or gold) with theoutline: 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.

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 anin prop. This corresponds to the open/close state.
• Call theonEnter callback prop when the enter transition starts.
• Call theonExited 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 forreact-transition-group.

Alternatively, you can usereact-spring.

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 responsivenessit might be a good idea to change this default behavior by enabling thekeepMounted prop:

<ModalkeepMounted/>

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

Reactdoesn't support thecreatePortal() API on the server.In order to display the modal, you need to disable the portal feature with thedisablePortal prop:

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:

<ModaldisableEnforceFocus/>

Accessibility

(WAI-ARIA:https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)

• Be sure to addaria-labelledby="id...", referencing the modal title, to theModal.Additionally, you may give a description of your modal with thearia-describedby="id..." prop on theModal.

  <Modalaria-labelledby="modal-title"aria-describedby="modal-description"><h2id="modal-title">My Title</h2><pid="modal-description">My Description</p></Modal>

  CopyCopied(or $keyC)

• TheWAI-ARIA Authoring Practices 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 areinert. That is, users cannot interact with content outside an active modal window. This might createconflicting behaviors.

API

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

• <Modal />