Skip to main content

Modal

A modal disables page content and focuses the user's attention on a single task or message.


Default Modal

Component Preview

Open default modal

Are you sure you want to continue?


Component Code

<a href="#example-modal" class="usa-button" aria-controls="example-modal" data-open-modal>Open modal</a>

<div class="usa-modal" id="example-modal" aria-labelledby="modal-heading" aria-describedby="modal-description">
  <div class="usa-modal__content">
    <div class="usa-modal__main">
      <h2 class="usa-modal__heading" id="modal-heading">Modal heading</h2>
      <div class="usa-prose">
        <p id="modal-description">Modal description.</p>
      </div>
      <div class="usa-modal__footer">
        <ul class="usa-button-group">
          <li class="usa-button-group__item">
            <button type="button" class="usa-button" data-close-modal>Continue</button>
          </li>
          <li class="usa-button-group__item">
            <button type="button" class="usa-button usa-button--unstyled" data-close-modal>Cancel</button>
          </li>
        </ul>
      </div>
    </div>
    <button type="button" class="usa-button usa-modal__close" aria-label="Close this window" data-close-modal>
      <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
        <use xlink:href="/assets/img/sprite.svg#close"></use>
      </svg>
    </button>
  </div>
</div>

Large Modal

Component Preview

Open large modal

Large Modal

You can include multiple paragraphs, lists, or other content as needed.


Component Code

<a href="#example-modal-lg" class="usa-button" aria-controls="example-modal-lg" data-open-modal>Open large modal</a>

<div class="usa-modal usa-modal--lg" id="example-modal-lg" aria-labelledby="modal-lg-heading" aria-describedby="modal-lg-description">
  <div class="usa-modal__content">
    <div class="usa-modal__main">
      <h2 class="usa-modal__heading" id="modal-lg-heading">Large Modal</h2>
      <div class="usa-prose">
        <p id="modal-lg-description">This is a large modal with more content space.</p>
      </div>
      <div class="usa-modal__footer">
        <ul class="usa-button-group">
          <li class="usa-button-group__item">
            <button type="button" class="usa-button" data-close-modal>Continue</button>
          </li>
          <li class="usa-button-group__item">
            <button type="button" class="usa-button usa-button--unstyled" data-close-modal>Cancel</button>
          </li>
        </ul>
      </div>
    </div>
    <button type="button" class="usa-button usa-modal__close" aria-label="Close this window" data-close-modal>
      <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
        <use xlink:href="/assets/img/sprite.svg#close"></use>
      </svg>
    </button>
  </div>
</div>

Forced Action Modal

Component Preview

Open forced action modal

Session expiring


Component Code

<a href="#example-modal-forced" class="usa-button" aria-controls="example-modal-forced" data-open-modal>Open forced action modal</a>

<div class="usa-modal" id="example-modal-forced" aria-labelledby="modal-forced-heading" aria-describedby="modal-forced-description" data-force-action>
  <div class="usa-modal__content">
    <div class="usa-modal__main">
      <h2 class="usa-modal__heading" id="modal-forced-heading">Session expiring</h2>
      <div class="usa-prose">
        <p id="modal-forced-description">Your session will expire in 5 minutes. Do you want to continue?</p>
      </div>
      <div class="usa-modal__footer">
        <ul class="usa-button-group">
          <li class="usa-button-group__item">
            <button type="button" class="usa-button" data-close-modal>Continue session</button>
          </li>
          <li class="usa-button-group__item">
            <button type="button" class="usa-button usa-button--unstyled" data-close-modal>End session</button>
          </li>
        </ul>
      </div>
    </div>
    <!-- Note: No close button for forced action modals -->
  </div>
</div>


Guidance

When to use the modal component

Confirmation dialogs
Use modals when you need the user to confirm a destructive or irreversible action.
Session timeouts
Alert users when their session is about to expire and give them the option to continue.
Important information
Display important information that requires immediate attention before the user can continue.

When to consider something else

Simple messages
For simple notifications that don't require user action, use an alert component instead.
Complex forms
Avoid putting complex forms inside modals. Consider a dedicated page instead.
Non-critical information
Don't use modals to show information that isn't essential. Modals interrupt the user's workflow.

Usability guidance

Keep content brief
Modal content should be concise and focused on a single task or message.
Provide clear actions
Make the available actions clear and easy to understand. Use descriptive button labels.
Allow easy dismissal
Unless using a forced action modal, users should be able to close the modal by clicking outside, pressing Escape, or using the close button.

Accessibility guidance

Focus management
When the modal opens, focus should move to the modal. When it closes, focus should return to the triggering element.
Keyboard navigation
Users should be able to close the modal with the Escape key (unless it's a forced action modal).
Use ARIA attributes
Use aria-labelledby and aria-describedby to provide accessible labels and descriptions.
Screen reader announcements
The modal component uses role="dialog" to announce the modal to screen readers.

USWDS Documentation

For more guidance, view the USWDS Modal Component Documentation.



Settings

Variable Description
$theme-modal-border-radius

Border radius of the modal window.
$theme-modal-lg-content-max-width

Maximum width of large modal content.
$theme-modal-lg-max-width

Maximum width of the large modal window.
$theme-modal-default-max-width

Maximum width of the default modal window.


Variants

Variant Description

.usa-modal--lg

Display a larger modal window.

data-force-action

Prevents closing the modal by clicking outside or pressing Escape. The user must interact with the modal buttons.
Looking for U.S. government information and services?
Visit USA.gov