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

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

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

Accessibility considerations

Edit this page in GitHub (Permissions required)
Last updated: May 14, 2025