Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.


The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.



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


View va-modal in Storybook

Crisis Line Modal

View va-modal in Storybook


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
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.

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.
Edit this page in GitHub (Permissions required)
Last updated: Apr 19, 2022