Note

This component uses Portals internally, which requires React 16

Note

This component uses ZLevel context internally, which requires React 16

Usage

Subcomponents

Modal role="dialog" aria-labelledby="a" howToClose
- Modal.Header (works with howToClose x)
  - Modal.Heading id="a" (semantic heading, link it to the dialog)
- Modal.Body
  - Modal.Section
    - Modal.Section
  - Modal.Heading (semantic synergy with Modal.Section heading)
- Modal.Footer
  - Modal.FooterSummary
  - Modal.FooterNotation
  - Modal.FooterButtons (works with howToClose footer-button)

Props

Name	Type	Required	Default	Description
aria-describedby	string	false
aria-details	string	false
aria-label	string	false		a11y `role='dialog'` MUST be labelled. Prefer `aria-labelledby` over `aria-label`. since 11.12.0 Accessibility notes: `role='dialog'` MUST be labelled. Prefer `aria-labelledby` over `aria-label`.
aria-labelledby	string	false		a11y `role='dialog'` MUST be labelled. Prefer `aria-labelledby` over `aria-label`. since 11.12.0 Accessibility notes: `role='dialog'` MUST be labelled. Prefer `aria-labelledby` over `aria-label`.
children	ReactNode	false
className	string	false		Additional classNames
howToClose	ModalOptionalCloseStartegy[]	false	[]	This adds additional UI or UX to close. Escape key will always close a dialog, see `onClose`. NOTE 'footer-button': Footer Cancel button still requires at least a rendered self closing `Modal.FooterButtons`. NOTE 'x': The X button still requires a rendered `Modal.Header` component. defaultvalue [] since 11.12.0
id	string	false		Aligns with `role` and `ref` location.
onClose	ModalOnClose	false		When a user closes the Modal by some approved `howToClose` method or the Escape key. This also opts-in to dialog focus management. a11y Future default! Moves focus into and cycles focus in the Modal, and returning focus to the trigger when closed. Also enables the Escape key to close the Modal. since 11.6.0 Accessibility notes: Future default! Moves focus into and cycles focus in the Modal, and returning focus to the trigger when closed. Also enables the Escape key to close the Modal.
open	boolean	false	false	Modal open state defaultvalue false since 10.19.0
placement	ModalPlacement	false	center	Vertical placement of the modal defaultvalue center since 10.19.0
role	"dialog"	false		Enable dialog props. REQUIRES `onClose` to enable Escape key and focus management. MUST be labelled, prefer `aria-labelledby` over `aria-label`.
style	CSSProperties	false		Additional CSS styles
width	ModalWidth	false		Sets a width on the container and uses next centering. Future will default to `md` since 10.19.0
onClickOverlay	Function	false		Callback for clicking the overlay since 10.19.0

A Modal has one requried way to close.

Modal onClose. This enables Escape key to close it. It also makes focus move into, trapped, and return out of the container. This starts to make Modal act like a modal dialog widget.

A Modal has many optional ways to close:

Modal onClickOverlay Clicking the scrim under the Modal.
Modal.Header onClose Adds an X icon button.
Modal.FooterButtons Button onClick Cancel Button.

Alternatively, you can use Modal howToClose={['x', 'scrim', 'footer-button']} to start to unify all the UI piece event handlers into one location.

Legacy: onClose scattered around.

Next: onClose only, and required, on Modal. See role=dialog.

role=dialog

For the next generation Modal:

Apply Modal onClose to enable focus management and Esc key support
Apply Modal role="dialog" to enable the role
Link the Modal component and a heading label, like by aria-labelledby
Leverage Modal onClose and customize UI with howToClose

placement

width

Change the width of the Modal.

If you are or were setting width properties on Modal, Modal.Body, or other subcomponents, look to use just width. Using this prop opts into the next gen layout and removes the max-width from Modal.Body. Eventually this layout improvement will always be used.

Modal.Header

Name	Type	Required	Default	Description
qa	{ closeButton?: string }	false
onClose	Function	false		since 10.19.0

Note: howToClose with x, it is still required to render a Modal.Header.

Modal.Heading

A component that inserts the correct HTML semantic heading level, based on parent (Header, Body, Section, nested Section).

Modal.Body

Name	Type	Required	Default	Description
noSideSpacing	boolean	false	false	Removes left, right paddings from the modal body when true defaultvalue false since 10.19.0

Modal.Section

Modal.Footer

Name	Type	Required	Description
children	ReactNode	false
className	string	false	Additional classNames
style	CSSProperties	false	Additional CSS styles

Modal.FooterSummary

Name	Type	Required	Description
children	ReactNode	false
className	string	false	Additional classNames
style	CSSProperties	false	Additional CSS styles

Currently using a Footer Summary requires a max width set on the footer or modal.

Modal.FooterNotation

Name	Type	Required	Description
children	ReactNode	false
className	string	false	Additional classNames
style	CSSProperties	false	Additional CSS styles

Modal.FooterButtons

Name	Type	Required	Description
children	ReactNode	false
className	string	false	Additional classNames
style	CSSProperties	false	Additional CSS styles

Note: howToClose with footer-button, it is still required to render a Modal.FooterButtons.

Use howToClose to enable "Cancel" in footer. It is still required to place a self closed Modal.FooterButtons component when using howToClose={['footer-button']}.

Overflow

ConfirmModal

Name	Type	Required	Default	Description
aria-describedby	string	false
aria-details	string	false
aria-label	string	false		a11y `role='dialog'` MUST be labelled. Prefer `aria-labelledby` over `aria-label`. since 11.12.0 Accessibility notes: `role='dialog'` MUST be labelled. Prefer `aria-labelledby` over `aria-label`.
aria-labelledby	string	false		a11y `role='dialog'` MUST be labelled. Prefer `aria-labelledby` over `aria-label`. since 11.12.0 Accessibility notes: `role='dialog'` MUST be labelled. Prefer `aria-labelledby` over `aria-label`.
children	ReactNode	false
className	string	false		Additional classNames
headline	string	false		Headline message since 10.19.0
howToClose	ModalOptionalCloseStartegy[]	false	[]	This adds additional UI or UX to close. Escape key will always close a dialog, see `onClose`. NOTE 'footer-button': Footer Cancel button still requires at least a rendered self closing `Modal.FooterButtons`. NOTE 'x': The X button still requires a rendered `Modal.Header` component. defaultvalue [] since 11.12.0
id	string	false		Aligns with `role` and `ref` location.
open	boolean	false	false	Modal open state defaultvalue false since 10.19.0
placement	ModalPlacement	false	center	Vertical placement of the modal defaultvalue center since 10.19.0
role	"dialog"	false		Enable dialog props. REQUIRES `onClose` to enable Escape key and focus management. MUST be labelled, prefer `aria-labelledby` over `aria-label`.
style	CSSProperties	false		Additional CSS styles
width	ModalWidth	false		Sets a width on the container and uses next centering. Future will default to `md` since 10.19.0
onClickOverlay	Function	false		Callback for clicking the overlay since 10.19.0
onClose	Function	false		The dismiss onClick callback since 10.19.0

Review Tearsheet docs to learn how Modal can work in tandem with Form enableConfirmNavigation when trying to close with unsaved data.

Modal