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:

Any content that is on the page, but outside of the modal, cannot be interacted with or navigated to while the modal is open.Learn more about trapping focus in our accessibility development guide for accessibility.
Standard keyboard navigation can be used to navigate between the contents of a modal.Tab navigates to the next focusable element inside a modal, and Shift + Tab navigates to the previous focusable element.
The Escape key should close the modal only if no other components within the modal are open.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.
There is at least one clickable button that will close the modal.For example, the close icon in the modal header or a 'cancel' button in the footer.
The modal content can receive focus via keyboard if it overflows and renders a scrollbar.
When a modal closes, focus should return to the last focused item before the modal was opened.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".