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.

Https

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.

Components

Modal

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

Examples - v1

Default

View va-modal in Storybook

Info

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

Crisis Line Modal

View va-modal in Storybook

Large

View va-modal large in Storybook

With button pair

View va-modal with button pair in Storybook

Examples - v3

Default

View va-modal v3 along with additional variations in Storybook

With forced action

View va-modal v3 with forced action in Storybook

Usage

Refer to the U.S. Web Design System for usage guidance

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

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
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. This is only available for USWDS
uswds uswds boolean false Whether or not the component will use USWDS v3 styling.
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.
component-library-analytics
click Used to detect clicks outside of modal contents to close modal.
keydown Used to detect Escape key to close modal.
focusin

Accessibility considerations

Refer to the U.S. Web Design System for accessibility guidance

Edit this page in GitHub (Permissions required)
Last updated: Aug 18, 2023