Modal

A modal is a window that overlays a page to display important information, without requiring users to navigate to a new page.

Accessibility

To implement an accessible PatternFly modal component:

  • Add an aria-label to the modal if it doesn't have a visible text title
  • Provide at least one clickable button that can close the modal, such as the default close icon or a "cancel" button
  • Ensure any other PatternFly components follow their respective accessibility documentation

Testing

At a minimum, a modal should meet the following criteria:

  • Learn more about trapping focus in our accessibility development guide for accessibility.
  • Tab navigates to the next focusable element inside a modal, and Shift + Tab navigates to the previous focusable element.
  • If a dropdown is open within an open modal, pressing Escape once should close the dropdown only, and pressing Escape again should close the modal itself.
  • For example, the close icon in the modal header or a 'cancel' button in the footer.
  • Exceptions to this include if the last focused item no longer exists, or if focusing another element makes more sense from a work flow perspective.

React customization

The following React props have been provided for more fine-tuned control over accessibility.

Prop
Applied to
Reason
aria-describedby="[id of the element that describes the modal"
Modal
Adds an accessible description to the modal. Typically this will be the id of the primary modal content.
aria-label="[text that labels the modal]"
Modal
Adds an accessible name to the modal. Required if there is no visible text that acts as the modal title, such as from the title or header props.
aria-labelledby="[id of the element that labels the modal]"
Modal
Adds an accessible name to the modal. Required if using the header prop rather than the title prop.
bodyAriaLabel
Modal
Adds an accessible name to the modal body. Required when the content of the modal body overflows and triggers a scrollbar.

When passed in, the accessible role of the modal body will be set to region by default.
bodyAriaRole
Modal
Adds an accessible role to the modal body. Passing this prop in will override the default region role when bodyAriaLabel is passed in.
disableFocusTrap
Modal
Disables the built-in focus trap functionality and allowing custom focus management when the modal is opened. When passing this prop in, you must manually trap focus yourself so that content outside of the open modal cannot be interacted with or navigated to.
title
Modal
Adds a visible text title to the modal and automatically sets the aria-labelledby of the modal. It is recommended to pass this prop in when also passing in the titleIconVariant prop to provide more context to users.
titleIconVariant
Modal
Adds an icon to the modal title. When passing in a custom icon that conveys status or severity, you must also pass in the titleLabel prop.
titleLabel
Modal
Adds visually hidden text before the modal title in order to describe the status or severity of the modal. If a predefined value is passed to titleIconVariant, the visually hidden text is automatically set to [variant] alert:, but can be overridden with this prop.

HTML/CSS customization

The following HTML attributes and PatternFly classes can be used for more fine-tuned control over accessibility.

Attribute or class
Applied to
Reason
aria-describedby="[id of the element that describes the modal"
.pf-v6-c-modal-box
Adds an accessible description to the modal. Typically this will be the id of the primary modal content.
aria-label="[text that labels the modal]"
.pf-v6-c-modal-box
Adds an accessible name to the modal. Required if there is no visible text that acts as the modal title.
aria-labelledby="[id of the element that labels the modal]"
.pf-v6-c-modal-box
Adds an accessible name to the modal. Required if .pf-v6-c-modal-box__title or another title element is present.
aria-modal="true"
.pf-v6-c-modal-box
Notifies users of assistive technologies that the contents underneath the modal are not available for interaction. This does not prevent other content from being interacted with, nor does it make the element a modal itself. Required.
role="dialog"
.pf-v6-c-modal-box
Identifies the element that serves as the modal container. Required.
aria-label="[text labeling the modal body]"
.pf-v6-c-modal-box__body
Adds an accessible name to the modal body. This attribute should only be passed in if the role attribute is also passed in. Required if the modal body content renders a scrollbar due to overflow.
role="[role of the modal body]"
.pf-v6-c-modal-box__body
Adds an accessible role to the modal body. Typically "region" is passed in as the role. Required if the modal body content renders a scrollbar due to overflow.
tab-index="0"
.pf-v6-c-modal-box__body
Makes the modal body focusable via keyboard and other assistive technologies. Required if the modal body content renders a scrollbar due to overflow.
aria-label="Close"
.pf-v6-c-modal-box__close .pf-v6-c-button
Adds an accessible name to the close button of a modal. Required.
form="[id of the form element in the modal body]"
.pf-v6-c-modal-box__footer .pf-v6-c-button
Links a "submit" button in the modal footer with a form in the modal body. Required when the submit button is outside of a <form> element.
aria-hidden="true"
.pf-v6-c-modal-box .pf-v6-c-button i, .pf-v6-c-modal-box__header-help .pf-v6-c-button i
Removes the close button and help button icons from the accessibility tree, preventing assistive technologies from potentially announcing duplicate or unnecessary information without visually hiding it. Required.
.pf-screen-reader
.pf-v6-c-modal-box__title span
Should be used to add text to the modal title that is accessible only to assistive technologies and is not visually rendered. The text content of this element should state the status or severity of the modal and should preface the modal title.
aria-hidden="true"
Parent element that contains the page contents
Removes the specified content from the accessibility tree, preventing assistive technologies from interacting with it. The .pf-v6-c-modal-box element must not be a descendent of the element that has this attribute. Required when the modal is open.

Additional considerations

Consumers must ensure they take any additional considerations when customizing a modal, using it in a way not described or recommended by PatternFly, or in various other specific use cases not outlined elsewhere on this page.

Focus

When a modal opens, the element that should receive focus will depend on the content and size of the modal. The following guidelines can help decide where to place focus for your use case.

  • If the modal contains semantic elements, such as lists or tables, that are necessary to perceive in order to better understand the modal content, place focus on a static element at the start of the content. The element that receives focus must have tabindex="-1".
  • If the modal includes an irreversible action, such as deleting data, place focus on the least destructive action in the modal.
  • If the modal includes actions that simply provide additional information or continue processing, such as an "OK" or "Continue" button, place focus on the action that is likely to be most frequently used.
  • If none of the above apply, place focus on the first focusable element in the modal.
  • If placing focus on an element would cause the beginning of the modal content to scroll out of view, focus should instead be placed on a static element at the top of the modal. Typically this would be the modal title, but can also be the first paragraph element. The element that receives focus in this way must have tabindex="-1".

Further reading

To read more about accessibility with a modal (also known as a dialog), refer to the following resources: