Pass an element ref to focus on a specific element on load. Default behavior is focus is moved to the first interactive element inside the modal dialog.

Contents of the modal dialog.

Callback function which lets you allowlist nodes so they can be interacted with outside of the focus lock. Return true if focus lock should handle element, false if not.

Height of the modal dialog. When unset the modal dialog will grow to fill the viewport and then start overflowing its contents.

Will remove the blanket tinted background color.

The label of the modal dialog that is announced to users of assistive technology. This should only be used if there is no modal title being associated to your modal, either via using the modal title component or the titleId prop within the useModal context.

Callback function called when the modal dialog is requesting to be closed.

Callback function called when the modal dialog has finished closing.

Callback function called when the modal dialog has finished opening.

Callback function called when the modal changes position in the stack.

Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref).

@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}

Calls onClose when pressing escape.

This prop will be removed in a future major release. Closing on escape is standard modal behaviour and should not be disabled. If you need to prevent closing during an in-progress async action, instead handle the onClose callback to block the action conditionally.

Calls onClose when clicking the blanket behind the modal dialog.

ReturnFocus controls what happens when the user exits focus lock mode. If true, focus returns to the element that had focus before focus lock was activated. If false, focus remains where it was when the FocusLock was deactivated. If ref is passed, focus returns to that specific ref element.

Will set the scroll boundary to the viewport. If set to false, the scroll boundary is set to the modal dialog body.

The stackIndex is a reference to the position (index) of the calling dialog in a modal dialog stack. New modals added to the stack receive the highest stack index of 0. As more modals are added to the stack, their index is dynamically increased according to their new position. Don't alter the modal stack position using stackIndex in implementations of third-party libraries (e.g. AUI modal), it may lead to unpredictable bugs, especially if the third party library has its own focus lock. Additionally, each modal in the stack gets a vertical offset based on stackIndex value.

A testId prop is provided for specified elements, which is a unique string that appears as a data attribute data-testid in the rendered code, serving as a hook for automated tests. If not overridden using testId prop in the respective components, this will set data-testid on these elements when defined:

• Modal dialog: {testId}
• Modal header: {testId}--header
• Close button: {testId}--close-button
• Modal title: {testId}--title
• Modal body: {testId}--body
• Modal footer: {testId}--footer
• Scrollable element: {testId}--scrollable
• Blanket: {testId}--blanket

@internal NOT FOR PUBLIC USE. This prop is used to disable the new motion uplift. It is strictly only used for cases where the motion uplift is not working as expected.

@warning Use with caution. This prop will be removed in a future release.

Width of the modal dialog. The recommended way to specify modal width is using named size options.

Children of modal dialog footer.

Determines whether inline padding will be applied. Defaults to true.

A testId prop is provided for specified elements, which is a unique string that appears as a data attribute data-testid in the rendered code, serving as a hook for automated tests.

Children of modal dialog header.

Shows a close button at the end of the header.

A testId prop is provided for specified elements, which is a unique string that appears as a data attribute data-testid in the rendered code, serving as a hook for automated tests.

Appearance of the modal that changes the color of the primary action and adds an icon to the title.

Children of modal dialog header.

When true will allow the title to span multiple lines. Defaults to true.

A testId prop is provided for specified elements, which is a unique string that appears as a data attribute data-testid in the rendered code, serving as a hook for automated tests.

Children of modal dialog footer.

A testId prop is provided for specified elements, which is a unique string that appears as a data attribute data-testid in the rendered code, serving as a hook for automated tests.

A boolean for if the onClose is provided. We define a noop as our onClose at the top level, but we need to know if one is provided for the close button to be rendered.

Whether or not the modal is fullscreen (when width="full" is passed to the modal).

Callback function called when the modal dialog is requesting to be closed, wrapped in modal dialog's analytic event context.

Test ID passed to the modal dialog.

Id referenced by the modal dialog's aria-labelledby attribute. This id should be assigned to the modal title element.