Modal

Components

Use: Deployed

A modal disables page content and focuses the user’s attention on a single task or message.

Examples

When the focus on the user must be focused on a single, or limited number, of elements. For example, when confirming or canceling a required action.
The flow the user is in would otherwise be interrupted by a distinct page.

Every time! Before using a modal, consider whether there’s another component that might be less disruptive for the user. Modals should be a last resort.
Content that must be linkable (have a distinct URL) or searchable.
Modals should not contain long forms.

Property	Attribute	Type	Default	Description
`ariaHiddenNodeExceptions`		`HTMLElement[]`	`[]`	Additional DOM-nodes that should not be hidden from screen readers. Useful when an open modal shouldn't hide all content behind the overlay.
`clickToClose`	`click-to-close`	`boolean`	`false`	Click outside modal will trigger closeEvent
`disableAnalytics`	`disable-analytics`	`boolean`	`false`	If true, analytics event won't be fired
`initialFocusSelector`	`initial-focus-selector`	`string`		Selector to explicitly specify which element should receive focus when the modal is open, if the initially focused element is not the first focusable element in the document
`large`	`large`	`boolean`	`false`	If `true`, modal will be wider.
`modalTitle`	`modal-title`	`string`		Title/header text for the modal
`primaryButtonText`	`primary-button-text`	`string`		Primary button text
`secondaryButtonText`	`secondary-button-text`	`string`		Secondary button text
`status`	`status`	`"continue" \| "error" \| "info" \| "success" \| "warning"`
`visible`	`visible`	`boolean`	`false`	If the modal is visible or not

Name	Description
`closeEvent`	Fires when modal is closed.
`component-library-analytics`	The event used to track usage of the component. Fires when a a page is selected if enable-analytics is true.
`primaryButtonClick`	Fires when primary button is clicked.
`secondaryButtonClick`	Fires when secondary button is clicked.
`click`	Used to detect clicks outside of modal contents to close modal.
`keydown`	Used to detect Escape key to close modal.
`focusin`

Modal should have the role=”dialog” attribute.
Content behind the modal should not scroll while the modal is open.
Modal should have an aria-labelledby attribute where the value is the ID of the modal title (you don’t need or want the #).
Modal should have an aria-describedby attribute where the value is the ID of a div that contains a description of the modal (you don’t need or want the #).
Pressing the ESC key should close the modal and return the focus to the element that triggered the modal.
If the modal contains a form, pressing the Enter key should submit that form.