Coming from Orbiter, you should be aware of the following changes:
dismissablehas been renamedisDismissable.onClosehas been removed, useonOpenChangeon the ModalTrigger instead.wrapperPropshas been renamedoverlayProps.
Modal
Modals focus the user’s attention exclusively on one task or piece of information via a window that sits on top of the page content.
Composed Components
A Modal uses the following components:
Usage
Default
A modal must have an heading and a content.
Image
A modal can have a side banner image. Make sure the image has no essential information as it could be cropped in mobile view. Images should not prevent a user from seeing the close button, be conscious of this.
Choice
A modal can offer a choice between 2 options. Keep the copy not too long in order to help the user quickly make his choice.
Header
Use an header to provide additional information usually in the form of a link or a tooltip that provides more context to the task at hand. Links should open in a new window.
Footer
Use a footer to provide trivial information about content present in the modal, like a step : 1/3.
Buttons
A modal can have a single button. Use a primary button to provide the main action.
Or a group of button. A maximum of 3 buttons are allowed in a modal, when necessary. The secondary and tertiary actions should be using a secondary variant.
Dismissable
By default, a modal will dismiss on outside interactions and esc keydown. However, in some cases, you might want to force the user to explicitly dismiss the modal with a targeted call to action.
This is what the isDismissable and the isKeyboardDismissDisabled prop is for.
You can set the isDismissable prop to false and isKeyboardDismissDisabled to true and render a call to action which will manually dismiss the popover by calling a close function.
Controlled
The open state can be handled in controlled mode.
Custom trigger
You don't have to use a ModalTrigger component if it doesn't fit your needs. A modal component can be used on it's own with any custom trigger.
Sizes
A modal can be small, medium, large, extra-large, fullscreen or fullscreenTakeover. The default size is medium.
Responsive sizes
A modal can have different size in mobile and desktop view.
Custom
A CustomModal is a Modal with a custom layout. A CustomModal must contain a <Heading slot="title"> or have an aria-label or aria-labelledby attribute for accessibility.
Props
Modal
isDismissible?
Whether the Modal is dismissable.
@deprecated Use isDismissable instead. This prop will be removed in a future version (September 30th, 2025).
Defaults to true.
isDismissable?
Whether the Modal is dismissable.
Defaults to true.
isKeyboardDismissDisabled?
Whether pressing the escape key to close the dialog should be disabled.
size?
The size of the modal.
Defaults to md.
overlayProps?
The props of the overlay
style?
The inline style for the element.
children?
Children of the dialog. A function may be provided to access a function to close the dialog.
className?
The CSS className for the element.
isOpen?
Whether the overlay is open by default (controlled).
defaultOpen?
Whether the overlay is open by default (uncontrolled).
ModalTrigger
isOpen?
Whether the overlay is open by default (controlled).
defaultOpen?
Whether the overlay is open by default (uncontrolled).
CustomModal
isDismissible?
Whether the Modal is dismissable.
@deprecated Use isDismissable instead. This prop will be removed in a future version (September 30th, 2025).
Defaults to true.
isDismissable?
Whether the CustomModal is dismissable.
Defaults to true.
isKeyboardDismissDisabled?
Whether pressing the escape key to close the dialog should be disabled.
size?
The size of the CustomModal.
Defaults to md.
overlayProps?
The props of the overlay
style?
The inline style for the element.
children?
Children of the dialog. A function may be provided to access a function to close the dialog.
className?
The CSS className for the element.
isOpen?
Whether the overlay is open by default (controlled).
defaultOpen?
Whether the overlay is open by default (uncontrolled).