Skip to content
EN

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.

Accessibility

  • 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>

Server-side modal

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