Skip to content

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.
  • 📦 5 kB gzipped.

Terminology note. 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.

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

Simple modal

Click to get the full Modal experience!

Notice that you can disable the outline (often blue or gold) with the outline: 0 CSS property.

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.

Alternatively, you can use react-spring.

Server-side modal

React doesn't support the createPortal() API on the server. In order to display the modal, you need to disable the portal feature with the disablePortal prop:

Accessibility

(WAI-ARIA: https://www.w3.org/TR/wai-aria-practices/#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.
    <Modal
aria-labelledby="modal-title"
aria-describedby="modal-description"
>
<h2 id="modal-title">
  My Title
</h2>
<p id="modal-description">
  My Description
</p>
</Modal>
  • The WAI-ARIA authoring practices can help you set the initial focus on the most relevant element, based on your modal content.
  • A modal window overlys 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.