Modal
How it works
The modal Carbon component is a secondary window that displays over the primary window to allow the user to maintain the context of a particular task. When the modal is displayed the primary window is inert, so users cannot interact with content outside an active modal.
The modal dialog contains the tab sequence so that Tab and Shift-Tab keys do not move the focus outside of the modal. To support screen reader users each modal component includes a WAI ARIA role="dialog" and aria-modal="true" so assistive technologies understand that the windows underneath the current dialog are not available for interaction (inert). Focus, accessible descriptions, and labels are set based on the content of each modal. Modals that contain static text have the aria-describeby property set on the element with the ARIA role="dialog" to indicate which element or elements in the dialog contain content describes the primary purpose or message of the dialog. A value is also set for the aria-labelledby property that refers to a visible dialog title.
Accessibility considerations
This component has been validated to meet the WCAG 2.0 AA and Section 508 accessibility guidelines, however changes made by the content owner can affect accessibility compliance. Be sure to review and follow the guidance in this section when updating or adding new content to this component.
- After the modal opens, initial focus should be set on the first focusable element in the modal. See WAI-ARIA Authoring Practices Modal Dialog Example, Accessibility Features section for best practices on setting focus.
- After a modal closes, focus should retain the user’s point of regard and return to the element that invoked the modal.
- Focus must not move outside the modal until it is closed.
- It is strongly recommended that the tab sequence of all modal dialogs include a visible element with button role that closes the dialog, such as a close icon or cancel button.
- Use the Alert modal dialog for special case that interrupts user’s workflow to communicate a brief, important message and require a user’s response,
Resources
Helpful resources for creating customized accessible implementations
- W3C WAI-ARIA Authoring Practices Dialog Modal Design Pattern covers the usage of ARIA names, state and roles, as well as the expected keyboard intractions.
- IBM Accessibility Checklist Checkpoint:
- 1.4.13 Content on Hover or Focus (WCAG Success Criteria 1.4.13)
- 2.1.2 No Keyboard Traps (WCAG Success Criteria 2.1.2)
- 2.4.3 Focus Order (WCAG Success Criteria 2.4.3)
Accessibility testing
Accessibility issues are tracked in the Carbon Component GitHub repository.
Automated test
Automated test environment
Results
- macOS Mojave version 10.14.6 with VoiceOver
- Chrome version 77.0.3865.90
- Dynamic Assessment Plugin version 1.8.0.0 - IBM Accessibility WCAG 2.1 Sept. 2019 Ruleset
- Carbon React version 7.7.1
- Chrome version 77.0.3865.90
- Dynamic Assessment Plugin version 1.8.0.0 - IBM Accessibility WCAG 2.1 Sept. 2019 Ruleset
- Carbon React version 7.7.1
DAP test
- No violations
- No violations
macOS Screen reader tests
Environment
Results
- macOS Mojave version 10.14.6 with VoiceOver
- Chrome version 77.0.3865.90
- Carbon React version 7.7.1
- Chrome version 77.0.3865.90
- Carbon React version 7.7.1
VoiceOver(VO) test:
- Tab to Launch modal button. VO announces the button label.
- Select Enter or Space key to launch the modal. VO announces the button label, headings, and text.
- Tab or Shift-Tab navigate through the modal buttons and announces each label.
- Select Control-Option-Right Arrow or Left Arrow to navigate through the modal message.
- Select the Esc key, Close button or Cancel button to close the modal and return focus to the Launch modal button in the primary window.
- macOS Mojave version 10.14.6 with VoiceOver
- Safari version 13.0.2
- Carbon React version 7.7.1
- Safari version 13.0.2
- Carbon React version 7.7.1
VoiceOver(VO) test:
- Tab to Launch modal button. VO announces the button label.
- Select Enter or Space key to launch the modal. VO announces the Button label.
- Tab or Shift-Tab navigate through the modal buttons and announces each label.
- Select Control-Option-Right Arrow or Left Arrow to navigate through the modal message.
- Select the Esc key, Close button or Cancel button to close the modal and return focus to the Launch modal button in the primary window.
Windows screen reader tests
Environment
Results
- Microsoft Windows 10
- Firefox version 67
- JAWS version 19.1810.64
- Carbon React version 7.7.1
- Firefox version 67
- JAWS version 19.1810.64
- Carbon React version 7.7.1
JAWS test:
- Tab to Launch modal button. JAWS announces the button label.
- Select Enter or Space key to launch the modal.
- Tab or Shift-Tab to navigate through the modal buttons and announces each label. Focus does not move out of the modal when tabbing.
- Select Control-Option-Right Arrow or Left Arrow to navigate through the modal message.
- Press Close button or Cancel button to close the modal and return focus to the Launch modal button in the primary window.
- Microsoft Windows 10
- Chrome version 73.0.3683.103 (Official Build) (64-bit)
- JAWS version 19.1810.64
- Carbon React version 7.7.1
- Chrome version 73.0.3683.103 (Official Build) (64-bit)
- JAWS version 19.1810.64
- Carbon React version 7.7.1
JAWS test:
- Tab to Launch modal button. JAWS announces the button label.
- Select Enter or Space key to launch the modal.
- Tab or Shift-Tab to navigate through the modal buttons and announces each label. Focus does not move out of the modal when tabbing.
- Select Control-Option-Right Arrow or Left Arrow to navigate through the modal message.
- Press Close button or Cancel button to close the modal and return focus to the Launch modal button in the primary window.
- Microsoft Windows 10
- Chrome version 73.0.3683.103 (Official Build) (64-bit)
- NVDA Version 2018.4.1
- Carbon React version 7.7.1
- Chrome version 73.0.3683.103 (Official Build) (64-bit)
- NVDA Version 2018.4.1
- Carbon React version 7.7.1
NVDA test:
- Tab to Launch modal button. NVDA announces the button label
- Select Enter or Space key to launch the modal. NVDA announces the text and buttons automatically.
- Tab or Shift-Tab to navigate through the modal buttons and announces each label. Focus does not move out of the modal when tabbing.
- Select Control-Option-Right Arrow or Left Arrow to navigate through the modal message.
- Press Close button or Cancel button to close the modal and return focus to the Launch modal button in the primary window.
Android screen reader tests
Environment
Results
- Android version 9 with Talkback
- Chrome Version 73.0.3683.103 (Official Build) (64-bit)
- Carbon React version 7.7.1
- Chrome Version 73.0.3683.103 (Official Build) (64-bit)
- Carbon React version 7.7.1
Talkback test:
- Swipe left or right, or use the Alt+Arrow keys in quick nav mode until you find the Launch modal button.
- Double tap the button or press the Alt-Enter keys to launch the modal. The close modal button is announces and has focus.
- Swipe Left or Right to explore the modal. VO announces the text, and focus on the Cancel and Save buttons.
- Note: that navigation is not restricted to the modal only, after the modal is open there is no way to know if there is an open modal present, the user needs to remember it. Doubletap or press Alt+Enter on the Close or Cancel buttons to close the modal.
iOS screen reader tests
Environment
Results
- iOS version 13.1.3 with VoiceOver
- Safari version 13.1.3
- Carbon React version 7.7.1
- Safari version 13.1.3
- Carbon React version 7.7.1
VoiceOver test:
- Swipe left or right, or use the Arrow keys in quick nav mode until you find the Launch modal button.
- Double tap the button to launch the modal. The close modal button is announces and has focus.
- Swipe Left or Right to explore the modal. VO announces the text, and focus on the Cancel and Save buttons.
- After Double tapping on the close or cancel button, the modal closes but focus is stuck on the selected button. Touch the screen anywhere to move out of the focus trap.