Modal

v8.6.2Edit this page

Standard, accessible modal component built on top of React Modal.

Usage

Loading...

Loading examples...

Props

<Modal>

Composes 1) BaseModal which composes react-modal 2) ModalContent which composes ModalHeader

Name

Description

Type

Default

aria

Additional ARIA attributes. This could be extended for more support

shape of:

{}

aria.labelledby

string

children

node

null

contentLabel

How the content container should be announced to screen readers

string

null

hasScrollLock

A boolean flag to allow consumers to opt out of the body-scroll-lock which is enabled by default. Useful for instances of full viewport modal on mobile. See https://nerdwallet.atlassian.net/browse/EM-3381

bool

true

shouldShowSecurityMessage

Flag to indicate if the encryption security message should be added to the modal.

bool

false

isOpen

Describes if the modal should be shown or not.

bool

onAfterOpen

Will be run after the modal has opened.

func

f => f

onRequestClose

Run when the modal is requested to be closed (either by clicking on overlay or pressing ESC) Note: It is not called if isOpen is changed by other means. If isOpen is set to false, will manually invoke this function.

func

f => f

shouldShowBack

Indicates if the back button should be shown.

bool

false

shouldCloseOnOverlayClick

Indicates if the modal should close when the overlay is clicked (clicking outside the modal)

bool

true

onRequestBack

Run after the modal's back button is clicked.

func

f => f

titleElementId

An id that will be given to the title's dom element, if provided

string

null

title

The title text of the modal

string

null

subtitle

The subtitle text of the modal

string

null

<Modal>

The <Modal> is an style-opinionated modal component that conforms to NDS guidelines. See react-modal's docs for set defaults.

Modal.setAppElement()

The app element is automatically set to #main, so you shouldn't need to use this when working in normal React apps, but it might be useful in other contexts like Storybook. See more info in the react-modal docs. If you are writing component tests you may need to have the tests run inside an HTML wrapper with id="main" set for the modal to render correctly in context.

<ModalHeader>

The title and subtitle can be set as props in <Modal>, but sometimes you may want to treat the title/subtitle as part of the content of the modal rather than a prop of the modal component. For example, when showing a multi-step form in a modal, you will probably want to build the title and subtitle into each component that represents a step in the multi-step form, rather than trying to make <Modal>'s parent component aware of which step is being shown in order to pull from some config object. For this reason <ModalHeader>, which is used internally by the <Modal> component, is exported for client use.

<BaseModal>

This is a bare bones wrapper on top of React Modal intended to be used to build custom modals that do not conform to the standard NerdWallet modal component (<Modal>). Only minimal styling has been applied (and some can be turned off).

Differences from React Modal

  • Always prevents body scroll while the modal is open. Due to this isOpen should never be hard coded to be true as overflow: hidden is only removed from the body when the modal is closed.
  • Always applies basic styling to the overlay in order to take over the entire viewport.
  • Prevents setting the shouldCloseOnEsc prop to false since we always want to enable this for accessibility
  • The styles prop has been excluded from this component's prop API as we don't do inline styling at NerdWallet.
  • A new prop, isCentered easily enables the common use case of centering a modal in the viewport.
  • A new prop, isScrollable easily enables scrolling when the modal height extends beyond the viewport.

BaseModal.setAppElement()

The app element is automatically set to #main, so you shouldn't need to use this when working in normal react apps, but it might be useful in other contexts like storybook. See more info in the react-modal docs.

Setting the right ARIA attributes

Best practice for modals is to provide a concise accessible name to the element which has the role. This is generally done with aria-labelledby pointing to the ID of the header. If no header is available then aria-label can be used. This is so that when you set focus to the modal, a screen reader user can better understand why and how the keyboard focus changed.

-- @dsturley

If your modal has a title, you can set the correct ARIA attributes like this:

or if you're using <ModalHeader> directly:

If your modal doesn't have a title, use the contentLabel prop:

Additional documentation

<Modal> and <BaseModal> are built on top of React Modal. See React Modal's docs for more in-depth usage information.

Maintainers

This component was created by Michael Ho (@mho).

See Also