Skip to main content
Hennepin County Design System

Modals

A modal is a pop-up that displays a message on top of other page content. A modal generally forces a user to complete a task or acknowledge a message. It prevents the user from interacting with the page until they close the modal. A modal can cover the whole page or part of it.

Use modals as a last resort. They have usability issues and disrupt the user. Use them only if no other component can do the action required.

Examples of modals:

  • A confirmation that a user has filled out a form and is ready to submit it
  • A privacy policy
  • A notification of a time limit to complete a task
  • A system error 

Modal title

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

HTML

    <div>
      <!-- button to trigger modal -->
      <button class="hc-button" data-open-modal>Open new modal</button>
    </div>

    <dialog 
      class="hc-modal" 
      data-modal
      aria-modal="true"
      aria-labelledby="modalTitle"
    >
      <div class="modal-header-and-close">
        <h3 id="modalTitle" class="hc-margin-bottom-00">Modal title</h3>
        <button 
          class="hc-button hc-button--icon-only" 
          aria-label="Close" 
          data-close-modal
        >
          <svg
            xmlns="http://www.w3.org/2000/svg"
            class="hc-icon-size--regular"
            viewbox="0 -960 960 960"
          >
            <path
             d="m256-200-56-56 224-224-224-224 56-56 224 224 224-224 56 56-224 224 224 224-56 56-224-224-224 224Z"
            />            
          </svg>
        </button>
      </div>

      <div class="modal-content">
        <p>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
          eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
          minim veniam, quis nostrud exercitation ullamco laboris nisi ut
          aliquip ex ea commodo consequat.
        </p>
      </div>

      <div class="button-group">
        <button
          type="button"
          class="hc-button hc-button--secondary btn-outline-primary"
          data-close-modal
        >
          Cancel
        </button>
        <button class="hc-button">Save changes</button>
      </div>
    </dialog>
A PrimeNG models component example.

Import

Label

When to use

  • As an alert or a required consent to process a form
  • When the user needs to give more information or clarify information
  • To notify a user that they have completed a process
  • To tell a user they are running out of time to do a task  

When not to use

  • For validation: Instead, use a validation component. They are less disruptive.  For more information, visit the validation component.
  • For confirmation: Instead, create a confirmation page. Or create an alert banner. For more information on alerts, visit the Alert banner component.
  • For step-by-step processes or questions: Instead, create individual pages.
  • For replacing the main page or landing page of a site: Instead, create an individual page.
Open all

Use the <dialog> element

The <dialog> element is a built-in modal dialog for HTML5. It offers features for dialog behavior, such as showing, hiding, and modal blocking. The <dialog> element includes JavaScript APIs .show(), .showModal(), and .close() for displaying and controlling the dialog. This makes it easy to show, hide, and interact with dialog content. Use the appropriate .showModal() or .show() method to display dialogs.

When using HTMLDialogElement.showModal(), the first nested element receives focus.

A .showModal() method will let users press the Esc key to close the modal. You do not need to use an ARIA role=”dialog” if you are using a <dialog> element.

Alert vs. alertdialog roles

Both roles help specify the type of modal message to users on assistive devices. Use <div> elements within the <dialog> to use the appropriate ARIA roles and attributes.

role = “alert”

This is a type of live region for important, immediate messages. This alert doesn’t make the user close the modal. This type of modal should not receive focus. This role has an implicit assertive value and will interrupt a user’s current task.

role= “alertdialog”

This is a type of live region for urgent messages that a user must respond to. Examples of this role include error messages or confirming a destructive action. The tab sequence must not leave the modal.  Users shouldn't be able to do anything else until they select an action within the modal.

Use the aria-describedby attribute to give greater context to the modal's content. The ID of the attribute must match the ID of the element referencing the content. It helps screen readers announce the descriptive content of the modal. The aria-labelledby attribute gives the modal an accessible name. It does this by connecting to the modal title or heading.

Keyboard accessibility

Make all modal content and controls keyboard accessible. Users should be able to open, close, and navigate the modal using the keyboard alone.

Close buttons

Include an obvious way a user can exit the modal. The .showModal() method allows a user to use the esc key to exit. But you should still have a close button or an “X” icon that is keyboard accessible.  

Make content and interactions clear and simple. Avoid too much information. Tell the user any issues they need to respond to. Give guidance on how to resolve those issues.

Make the content relevant to the user’s current task or context.

Make the modal easy to control. Make it easy for users to open and close the modal.

Make it clear what caused the modal to appear. Users should understand why the modal has displayed and how to respond.   

Open all