Modal

When to use

• 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:
    • “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).
• 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. 
• 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.

Accessibility guidance - NEEDS CHECK

• Label the modal with its heading. Use aria-labelledby=”[id]” on .usa-modal to read out the modal title when opening the modal. The [id] should match the value of the id attribute on the usa-modal__heading element.
• Share more context with aria-describedby. Optionally, you may also 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 modals - NEEDS CHECK

• 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 as either <button> or <a> elements. 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 type="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.