OverlayPanel

• accessibilityDismissButtonLabel: provides a short, descriptive label for screen readers as a text alternative to the Dismiss button. Populates the aria-label attribute on the Dismiss button.
• accessibilityLabel: provides a short, descriptive label for screen readers to contextualize the purpose of OverlayPanel. Please don’t repeat the same text being passed in the heading prop, but instead provide something that summarizes the OverlayPanel’s purpose. For instance, if the heading is "Pin Builder", the accessibilityLabel can be "Create a new Pin". Populates the aria-label attribute on the entire dialog.

When OverlayPanel opens, focus should be placed on the first interactive element within the OverlayPanel. When OverlayPanel is closed, focus should be placed back on the button that triggered the OverlayPanel.

As a default, OverlayPanel consists of a heading and content passed as children. The heading of OverlayPanel will have a drop shadow when content scrolls under it.

A subHeading is a container that can be used for additional navigation or sub-text. The sub-heading sits at the top under the heading, and will always remain visible if the content scrolls.

The footer is used for OverlayPanel tasks that require additional actions, such as submitting or deleting information.

OverlayPanel comes in 3 sizes: small (sm), medium (md), and large (lg).

• Small OverlayPanels (540px) are primarily used for displaying information or acting as a point to link to other content. They are the least commonly used.
• Medium OverlayPanels (720px) are the standard size offered for content.
• Large OverlayPanels (900px) should be used in cases where there may be columns of content or navigation where the additional space is required to keep the content at a comfortable reading width.

By default, users can click outside OverlayPanel (on the overlay) to close it. This can be disabled by setting closeOnOutsideClick to false. This may be implemented in order to prevent users from accidentally clicking out of the OverlayPanel and losing information they’ve entered. The ESC key can still be used to close the OverlayPanel.

By default, OverlayPanel animates in, with the initial render process from the entry-point, and out, when the ESC key is pressed, the header close button is pressed, or the user clicks outside of the OverlayPanel. However, to trigger the exit-animation from other elements inother areas such as the children or footer, the following render prop can be used:

<OverlayPanel.DismissingElement>
  ({ onDismissStart }) => ( ... )
</OverlayPanel.DismissingElement>

When using this render prop, just pass the argument onDismissStart to your exit-point action elements. In the example below, we've added the exit animation to the:

• Close button (subHeading)
• Right arrow icon red button (children)
• Done red button (children)
• Left arrow red icon button (children)
• Close button (footer)

OverlayPanel also provides onAnimationEnd, a callback that gets triggered at the end of each animation. The callback has access to animationState to identify the end of each 'in' and 'out' animation for cases where the two events trigger different responses.

There are two ways OverlayPanel can be dismissed: internally-controlled and externally-controlled dismiss actions.

The three internally-controlled or component-controlled dismiss actions are:

• when the ESC key is pressed
• when the backdrop is clicked
• when the dismiss IconButton is clicked

The externally-controlled dismiss actions (subHeading, children, and footer) require implementing the callback onDismissStart. See the animation variant to learn more.

OverlayPanels can contain forms or be part of flows where the user is required to submit infomation. If an OverlayPanel is dismissed involuntarily, the data entered by the user could not be saved and lost. This can create a bad user experience.

To prevent dismissing OverlayPanel involuntary, we can use dismissConfirmation. When provided, it will open a confirmation modal each time component-controlled dismiss actions are triggered.

The confirmation modal has a flexible API. When the dismissConfirmation prop is set to an empty object "dismissConfirmation={{}}", OverlayPanel uses default texts and labels. See the default content below:

• Message: "Are you sure you want to dismiss?"
• Subtext: "You will lose all of your changes. This cannot be undone."
• Primary action text: "Yes, dismiss."
• Primary action label: "Yes, dismiss the overlay panel."
• Secondary action text: "No, go back."
• Secondary action label: "No, go back to the overlay panel."

All texts and labels can be customized using the dismissConfirmation prop. We can pass an object with custom strings. For any missing strings, OverlayPanel uses the default ones. See the dismissConfirmation prop Flow type to learn more about the optional texts and labels than can be customized.