Components
Modal
Use: Deployed
A modal disables page content and focuses the user’s attention on a single task or message.
Examples
Crisis Line Modal
Usage
When to use a modal
- 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.
When to consider something else
- 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.
Code usage
Attributes and Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
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 | |
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 |
Events
| 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 |
Accessibility considerations
- 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.