Components
Modal
Use: Best practice
USWDS v3
A modal disables page content and focuses the user’s attention on a single task or message.
Examples
Default
View va-modal in StorybookInfo
View va-modal info in Storybook
Continue
View va-modal continue in Storybook
Success
View va-modal success in Storybook
Warning
View va-modal warning in Storybook
Error
View va-modal error in Storybook
Click outside to close
View va-modal click outside to close in Storybook
Without buttons
View va-modal without buttons in Storybook
Without title
View va-modal without title in Storybook
With nested web components
View va-modal with nested web components in Storybook
Large
View va-modal large in Storybook
With forced action
View va-modal with forced action in Storybook
Usage
Additional guidance for VA
When to consider something else
- Content that must be linkable (have a distinct URL) or searchable. Modals cannot be linked to or searched.
- Modals should not contain long forms. Modal content must be brief and not include complicated interactions.
Code usage
Attributes and Properties
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
forcedModal
forced-modal
boolean
false
Whether or not the component will be forced to take action.
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"
unstyled
unstyled
boolean
false
Whether or not the component will be using the unstyled button.
visible
visible
boolean
false
If the modal is visible or not
Events
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.
component-library-analytics
click
Used to detect clicks outside of modal contents to close modal.
keydown
Used to detect Escape key to close modal.