Skip to content

Modal

Status: Stable

Latest released: 2018

Current version: v8.10.1

Storybook
GitHub

Standard, accessible NerdWallet modal. Built on top of the 3rd party react-modal package     .


Variants

Basic

With Secure Encryption Message


Accessibility

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, aria-label can be used. This enables a screen reader user to better understand why and how the keyboard focus changed, when you set focus to the modal.

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

<Modal
title="My label"
titleElementId="my-title-id"
aria={{
labelledby: 'my-title-id',
}}
/>

or if you're using <ModalHeader> directly:

<Modal
aria={{
labelledby: 'my-title-id',
}}
>
<ModalHeader
titleElementId="my-title-id"
title="My label"
/>
</Modal>

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

<Modal
contentLabel="My label"
/>

Development

import Modal from '@nerdwallet/react-modal';
<Modal>Content here...</Modal>

The underlying react-modal library needs to know the root of your application so it can hide it via the aria-hidden attribute when the modal is open. This "app element" is automatically set to #main, so you shouldn't need to change this when working in normal React apps. However, if you're working in other contexts like Storybook, you may wish to change this app element:

import Modal from '@nerdwallet/react-modal';
Modal.setAppElement('#other-query-selector-here');

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.

See more info in the react-modal docs on app-element     .

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

Open in Playroom

It's important that a single unique value is supplied to the titleElementId prop on both the <Modal> and the <ModalHeader>. This allows screen readers to correctly announce the modal when it is opened.

Props

<Modal>

onRequestBack

Function

Run after the modal's back button is clicked.


shouldShowSecurityMessage

boolean

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


shouldShowBack

boolean

Indicates if the back button should be shown.


titleElementId

string

unique id for the title's dom element. If not provided, an autogenerated id will be used.


title

string

The title text of the modal


subtitle

string

The subtitle text of the modal


aria

Object

Deprecated

Additional ARIA attributes. This could be extended for more support @deprecated

{
labelledby: string
}

closeTimeoutMS

number

Deprecated

Duration for modal visual animations @deprecated


contentLabel

string

Deprecated

How the content container should be announced to screen readers @deprecated


onAfterOpen

Function

Deprecated

Will be run after the modal has opened. @deprecated


onRequestClose

Function

Deprecated

Will be 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. @deprecated