Modals

StackupUI provides CSS classnames and recommended HTML markup for modal backdrops and windows, but no implementation functionality is provided. It is strongly recommended, however, that its used in conjunction with the ReactModal package, which is easy to use, easy to adapt for StackupUI markup, and provides accessibility features.

<div role="dialog" aria-labelledby="modal-example__title" aria-describedby="modal-example__description" className="modal">
  <div className="modal__window">
    <h1 id="modal-example__title" className="heading-primary">An example modal</h1>
    <p id="modal-example__description">...</p>
    <div className="modal__actions"><!-- Action buttons here --></div>
    <div className="modal__dismiss"><!-- Dismiss buttons here --></div>
  </div>
</div>

import ReactModal from "react-modal"
...
ReactModal.setAppElement("#root") // Do this somewhere once
...
<ReactModal
  isOpen={true/false}
  overlayClassName="modal"
  className="modal__window"
  contentLabel={"An example modal"}
  aria={{
    labelledby: "modal-example__title",
    describedby: "modal-example__description"
  }}
>
  // Contents of .modal__window here
</ReactModal>

Accessibility concerns

For sighted users, it can be fairly clear that by placing an obscuring backdrop over the main content, it signifies that a certain action is required. For low or non-sighted users, this may not be obvious. Opening a modal is a significant and sudden change in the UI and the user's context within it.

ARIA attributes

In order for accessibility tools to properly understand and announce that a modal dialog has opened, its important to use the correct element roles and ARIA attributes.

• role="dialog" must be present on the outermost element that appears when the modal opens. This helps assistive tools to identify and announce the modal.
• aria-labelledby or aria-label must be used on the same element, which helps to identify the purpose of the dialog to a user.
• aria-describedby can be used to identify additional information about the dialog's purpose.

Managing focus

When a modal dialog is opened, the users focus should be "trapped" within the dialog, preventing them from accessing any content or controls outside the dialog. When the dialog is closed, focus should be returned to the element that opened the dialog, if there is such an element, or else to the main content of the original screen.

There are a few ways to achieve these, and this documentation won't go into detail on all of them. ReactModal implements these behaviors by default and correctly.