Skip to main content

Official website

of the Commonwealth of Pennsylvania

    The .gov means it's official.

    Local, state, and federal government websites often end in .gov. Commonwealth of Pennsylvania government websites and email systems use "pennsylvania.gov" or "PA.gov" at the end of the address. Before sharing sensitive or personal information, make sure you're on an official state website. 
    Components

    Modal

    A modal overlays the the main content on a webpage. The user has to dismiss the modal before they can interact with the main content.

    Overview

    Modals get the user's attention by appearing as an overlay above the main webpage content. They interrupt the user's workflow by design.

    When a modal is active, the user is unable to interact with the main page content. They can't return to their previous workflow until the modal task is completed or the user dismisses the modal. 

    While modals can be effective when used correctly, they should be used sparingly.

    When to use a modal

    If you need an immediate response from the user

    Use a dialog to request information that is preventing the system from continuing a user-initiated process.

    To notify the user of urgent information

    Use a modal dialog to notify the user of urgent information concerning their current work. Modal dialogs are commonly used to report system errors or convey a consequence of a user’s action.

    To confirm a user decision

    Use a modal dialog to confirm user decisions. Clearly describe the action being confirmed and explain any potential consequences that it may cause. Both the title and the button should reflect the action that will occur. If the action is destructive or irreversible then use a transactional danger modal.

     

    When to use another component

    Only use modals to provide notifications to the user if the information is critical to their task. For other notifications, consider using an in-page alert or a toast. These are less disruptive to the user.

    Formatting

    Anatomy

    A screenshot of a modal with numbers indicating where elements appear. The modal container includes an exclamation mark icon, a heading, a text link, and a link styled as a button.
    1. Container
    2. Icon (optional)
    3. Close icon button – selecting the button closes the modal window without submitting any data
    4. Heading
    5. Body copy
    6. Primary call to action with an optional icon Icon optional
    7. Secondary call to action
    8. Overlay – obscures the on-page content

    Behaviors

    Triggers

    Modals are triggered as a result of a user’s action. Buttons, links, or icons are common components that trigger a modal. On a keyboard, typing Enter or space bar should launch the modal.

    A modal can be closed by clicking on the close icon or typing Esc.

    Focus

    When a modal window opens, focus moves to the close button inside the window. Focus should remain trapped in the modal until it is closed. When navigating by keyboard, Tab and Shift-Tab do not move the focus outside of the modal.

    Tab:

    • Moves focus to the next focusable element inside the window.
    • If focus is on the last focusable element inside the window, Tab moves focus to the first focusable element inside the window.

    Shift + Tab:

    • Moves focus to the previous focusable element inside the window.
    • If focus is on the first focusable element inside the window, Tab moves focus to the last focusable element inside the window.

    Esc: 

    • Closes the window. Keyboard focus returns to the component that opened the modal.