Components

Modal

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

About the modal

A modal prevents interaction with page content until the user completes an action or dismisses the modal. This intentionally interrupts the user’s workflow. Use modals sparingly to minimize unnecessary disruptions.

Modals should have a simple headline that explains its purpose. Use enough descriptive text to be clear what the user needs to do and why. Avoid using modals to display complex forms or large amounts of information.

When to use the modal

  • Confirmation. Use modals to force the user to complete a task or make a decision that requires their full attention outside of the main workflow. These modals are usually triggered by a user action on the page and offer more than one option to proceed — such as a “yes” and “no” button. They are commonly used to confirm user actions or tasks that can’t be undone.

    Examples:

    • “Your work isn’t saved. Do you want to proceed?”
    • “Are you sure you want to cancel?”
  • Acknowledgement before continuing. These modals are used as a “gate” to prevent users from moving forward without acknowledging or answering specific information in the modal. A key differentiator of these modals is that a user should not be able to close the modal or escape without making a selection — this means the “close” button should be disabled on these modals. It also means there needs to be a clear way to accept or reject the content in the modal.

    Examples:

    • “By using this website, you are agreeing to our privacy policy.”
    • “Your session is about to timeout. Do you need more time?”
    • “Are you 65 or older?”
  • Explanatory content without disrupting a process. A modal can be used to display information without taking users away from a process or task. These modals usually show optional information to help a user gain further understanding about what they’re doing — for instance, displaying a privacy policy while creating an account or viewing an in-depth definition or explanation while filling out a form. Typically these modals don’t require a user to take action other than closing it.

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.

  • Multi-step process. Avoid complicated user flows in a modal that may take the user away from the original page. A multi-step process is better suited to an individual page, guiding the user and accommodating complexities in the user flow.

  • Error, success, or warning messages. When these relate to a form field, these are better displayed in the context of the page (such as showing an error next to a missing required field). When these relate to page-level messages (such as confirming that a form has been successfully submitted), they should appear as an alert at the top of the page where the user is taken next.

Usability guidance

  • Users should trigger modals. Modals should appear as a result of an action made by the user or (less commonly) inactivity. A modal should not surprise the user, so don’t automatically display them. Some exceptions would be to alert the user that their authenticated session in a web application is about to expire due to inactivity or if information needs to be displayed when arriving at a webpage for the first time (like accepting the use of cookies).

  • Choose the modal size that fits your content. There are two sizes to choose from: default and large. If a modal’s content can’t fit without scrolling, you may need to use the large variant or consider moving the content to its own page.

  • Use clear header and button text. The header should clearly state what’s happening or what action the modal is prompting the user to do. The button text should indicate what will happen when selected and avoid ambiguity. For example, if a modal asks “Do you want to cancel?” the button options should not be “yes” and “cancel” — instead use something like “Yes, cancel” and “No, don’t cancel.”

  • Limit in-modal interactions. Avoid using components other than buttons inside the modal. Components such as accordions and form fields often don’t scale well for mobile users and they can easily lose context that they’re viewing a modal. If you need to include links that navigate away from a modal to another webpage, refer to our link guidance about how to handle external links.

  • Consider what happens when the modal is dismissed. The page underneath should not reload or change to new content.

  • Avoid long content that requires scrolling. If a lot of content is needed, make sure it’s clear that users have to scroll to see all of it. Lengthy content can be problematic because it pushes buttons out of a user’s initial view, which may cause confusion.

  • Don’t roadblock external links with a modal window or dialog box. Allow users to follow external links without taking a separate action to acknowledge leaving your site. Roadblock notices result in a poor user experience and are redundant with both the link’s destination context and your site’s policies and notices page (see Link guidance).

Accessibility

  • Identify the title. Use aria-labelledby=”id” on .usa-modal to associate a title to the modal so that it’s read when opening the modal. The id should belong to the id attribute on .usa-modal__heading.

  • Descriptions. Optionally, you may use aria-describedby=”id” on .usa-modal to associate descriptive text to the modal window so that it’s read when opening the modal. The id should belong to a paragraph or a brief piece of content.

  • Include the “X” close button at the end of the modal code. CSS will display .usa-modal__close at the top right of the modal window, but placing the close button at the bottom of the modal will prevent some screen readers from reading the close button first and allow users to navigate directly to the main content instead.

Using the modal

  • Use unique ids. Each .usa-modal must have a unique id so that openers can associate them with their aria-controls attribute.

  • Openers. A single modal can have multiple openers. Each opener requires data-open-modal and aria-controls=”MODAL_ID” attributes. Openers can be coded either as <button> or <a>. Using <a> helps link to modals in the event javascript fails.

  • Closers. Place a data-close-modal attribute on any button that will close a modal. Closers may have event listeners attached to them. Code closers as <button>.

  • Disabling close when an action is required. In instances that a user must make a choice before continuing, you want to prevent them from closing the modal without taking action. Add data-force-action attribute to .usa-modal to prevent the user from closing the modal without taking an action.

Modal settings

Variable Description
$theme-modal-border-radius

The border radius of the modal window.

$theme-modal-default-max-width

Maximum width of default modal window.

$theme-modal-lg-max-width

Maximum width of large modal window.

$theme-modal-lg-content-max-width

Maximum width of content area within large modal window.

Modal variants

Variant Description

.usa-modal--lg

Add .usa-modal--lg to .usa-modal for a larger window and larger heading size on wider screens.

  • Package usage: @import usa-modal
  • Requires: required, global, usa-button