Warning alert:Deprecated feature
Examples
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%".
Custom header and footer
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.
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.
Props
Modal
| Name | Type | Default | Description |
|---|---|---|---|
| childrenrequired | React.ReactNode | Content rendered inside the modal. | |
| actions | any | [] | Action buttons to add to the standard modal footer. Ignored if the footer property is passed in. |
| appendTo | HTMLElement | (() => HTMLElement) | () => document.body | The parent container to append the modal to. Defaults to "document.body". |
| aria-describedby | string | '' | Id to use for the modal box descriptor. |
| aria-label | string | '' | Accessible descriptor of the modal. |
| aria-labelledby | string | '' | Id to use for the modal box label. |
| bodyAriaLabel | string | Accessible 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. | |
| bodyAriaRole | string | Accessible 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. | |
| className | string | '' | Additional classes added to the modal. |
| description | React.ReactNode | Description of the modal. | |
| disableFocusTrap | boolean | Flag to disable focus trap. | |
| elementToFocus | HTMLElement | SVGElement | string | The element to focus when the modal opens. By default the first focusable element will receive focus. | |
| footer | React.ReactNode | Custom footer. | |
| hasNoBodyWrapper | boolean | false | Flag indicating if modal content should be placed in a modal box body wrapper. |
| header | React.ReactNode | Complex header (more than just text), supersedes the title property for header content. | |
| help | React.ReactNode | Optional help section for the modal header. | |
| id | string | undefined | An id to use for the modal box container. |
| isOpen | boolean | false | Flag to show the modal. |
| maxWidth | number | string | Maximum width of the modal. | |
| onClose | (event: KeyboardEvent | React.MouseEvent) => void | () => undefined as any | A callback for when the close button is clicked. |
| onEscapePress | (event: KeyboardEvent) => void | Modal handles pressing of the escape key and closes the modal. If you want to handle this yourself you can use this callback function. | |
| ouiaId | number | string | Value to overwrite the randomly generated data-ouia-component-id. | |
| ouiaSafe | boolean | true | Set 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. |
| positionOffset | string | Offset from alternate position. Can be any valid CSS length/percentage. | |
| showClose | boolean | true | Flag to show the close button in the header area of the modal. |
| title | React.ReactNode | '' | Text content of the modal header. |
| titleIconVariant | 'success' | 'danger' | 'warning' | 'info' | 'custom' | React.ComponentType<any> | null | Optional 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. |
| titleLabel | string | '' | Optional title label text for screen readers. |
| variant | 'small' | 'medium' | 'large' | 'default' | 'default' | Variant of the modal. |
| width | number | string | Default width of the modal. |
CSS variables
| Expand or collapse column | Selector | Variable | Value |
|---|
