A modal displays important information to a user without requiring them to navigate to a new page.


Basic modals

Basic modals give users the option to either confirm or cancel an action. To flag an open modal, use the isOpen property. To execute a callback when a modal is closed, use the onClose property.

Scrollable modals

To enable keyboard-accessible scrolling of a modal’s content, pass tabIndex={0} to the <Modal>.

With a static description

To provide additional information about a modal, use the description property. Descriptions are static and do not scroll with other modal content.

Top aligned

To override a modal's default center alignment, use the position property. In this example, position is set to "top", which moves the modal to the top of the screen.

Small modal

To adjust the size of a modal, use the variant property. Modal variants include "small", "medium", "large", and "default".

The following example displays a "small" modal by passing in variant={ModalVariant.small}.

Medium modal

The following example displays a "medium" modal by passing in variant={ModalVariant.medium}.

Large modal

The following example displays a "large" modal by passing in variant={ModalVariant.large}.

Custom width

To choose a specific width for a modal, use the width property. The following example has a width of "50%".

To add a custom header and footer to a modal, set the header and footer properties to a custom implementation. The following example passes title components into both the header and the footer and also passes an icon to the footer.

To exclusively present information in a modal, remove the header and/or footer.

Title icon

To add an icon before a modal’s title, use the titleIconVariant, which can be set to one of the predefined variants -- "success", "danger", "warning", "info", and "custom" -- or to an imported custom icon. The following example uses a "warning" variant.

Custom title icon

To add a custom icon before a modal’s title, set titleIconVariant to an imported custom icon. The following example imports and uses a bullhorn icon.

With wizard

To guide users through a series of steps in a modal, you can add a wizard to a modal. To configure the <Wizard>, pass an array that contains a “name” and “component” value for each step into the steps property.

With dropdown

To present a menu of actions or links to a user, you can add a dropdown to a modal. To allow the dropdown to visually break out of the modal container, set the menuAppendTo property to “parent”. Handle the modal’s closing behavior by listening to the onEscapePress callback on the <Modal> component. This allows the "escape" key to collapse the dropdown without closing the entire modal.

With help

To help simplify and explain complex models, add a help popover. Only place a help icon at the modal level if its information applies to all content in the modal. If the help popover is specific to a particular modal section, place the help icon beside that section instead.

With form

To collect user input within a modal, you can add a form.

To submit the form from a button in the modal's footer (outside of the <Form>), set the button's form property equal to the form's id.

Custom focus

Use the elementToFocus property to customize which element inside the Modal receives focus when initially opened.


childrenrequiredReact.ReactNodeContent rendered inside the modal.
actionsany[]Action buttons to add to the standard modal footer. Ignored if the footer property is passed in.
appendToHTMLElement | (() => HTMLElement)() => document.bodyThe parent container to append the modal to. Defaults to "document.body".
aria-describedbystring''Id to use for the modal box descriptor.
aria-labelstring''Accessible descriptor of the modal.
aria-labelledbystring''Id to use for the modal box label.
bodyAriaLabelstringAccessible label applied to the modal box body. This should be used to communicate important information about the modal box body div element if needed, such as that it is scrollable.
bodyAriaRolestringAccessible role applied to the modal box body. This will default to "region" if the bodyAriaLabel property is passed in. Set to a more appropriate role as applicable based on the modal content and context.
classNamestring''Additional classes added to the modal.
descriptionReact.ReactNodeDescription of the modal.
disableFocusTrapbooleanFlag to disable focus trap.
elementToFocusHTMLElement | SVGElement | stringThe element to focus when the modal opens. By default the first focusable element will receive focus.
footerReact.ReactNodeCustom footer.
hasNoBodyWrapperbooleanfalseFlag indicating if modal content should be placed in a modal box body wrapper.
headerReact.ReactNodeComplex header (more than just text), supersedes the title property for header content.
helpReact.ReactNodeOptional help section for the modal header.
idstringundefinedAn id to use for the modal box container.
isOpenbooleanfalseFlag to show the modal.
maxWidthnumber | stringMaximum width of the modal.
onClose(event: KeyboardEvent | React.MouseEvent) => void() => undefined as anyA callback for when the close button is clicked.
onEscapePress(event: KeyboardEvent) => voidModal handles pressing of the escape key and closes the modal. If you want to handle this yourself you can use this callback function.
ouiaIdnumber | stringValue to overwrite the randomly generated data-ouia-component-id.
ouiaSafebooleantrueSet the value of data-ouia-safe. Only set to true when the component is in a static state, i.e. no animations are occurring. At all other times, this value must be false.
position'default' | 'top''default'Position of the modal. By default a modal will be positioned vertically and horizontally centered.
positionOffsetstringOffset from alternate position. Can be any valid CSS length/percentage.
showClosebooleantrueFlag to show the close button in the header area of the modal.
titlestring''Simple text content of the modal header. Also used for the aria-label on the body.
titleIconVariant'success' | 'danger' | 'warning' | 'info' | 'custom' | React.ComponentType<any>nullOptional alert icon (or other) to show before the title of the modal header. When the predefined alert types are used the default styling will be automatically applied.
titleLabelstring''Optional title label text for screen readers.
variant'small' | 'medium' | 'large' | 'default''default'Variant of the modal.
widthnumber | stringDefault width of the modal.

CSS variables

Expand or collapse columnSelectorVariableValue

View source on GitHub