Components/Overlays/Modal
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/modal
Modal is the overlay that appears as the background for all types of modal layouts. It is triggered by a user's action and is a container for components like <CustomModalLayout/> and <MessageModalLayout/>.
Modal consists of an overlay only and should contain one of the following layouts:
<CustomModalLayout/><ModalPreviewLayout/><AnnouncementModalLayout/><ModalMobileLayout/>Control the spacing between the viewport and the modal content by using screen prop. It has 3 options:
full (default) - used with <ModalPreviewLayout/>.desktop - used with all major desktop modals.mobile - used with <ModalMobileLayout/> component.Add the option to navigate between modals by using the showNavigationPreviousButton and showNavigationNextButton props.
By default, modal layouts do not allow content to overflow into the background.
Use popoverProps, appendTo and dynamicWidth props to display overlays as intended. For more guidance, read about the <Popover/> component.
| Name | Type | Default | Description |
|---|---|---|---|
appElement | string | — | Selector specifying where to apply the aria-hidden attribute. |
borderRadius | number | 0 | Border radius of modal. |
children | ReactNode | — | Renders modal content. |
closeTimeoutMS | number | 500 | Number indicating the milliseconds to wait before closing the modal. |
contentLabel | string | — | Sets the aria-label of the modal element. It helps assistive technology, like screen readers, to label an element that would otherwise be anonymous. |
dataHook | string | — | Applied as data-hook HTML attribute that can be used to create driver in testing. |
height | string | '100%' | Sets the height for modal's content container. |
horizontalPosition | "center" | "end" | "start" | 'center' | Horizontal position of the modal. |
isOpen (required) | boolean | — | Controls if modal is open or closed. |
maxHeight | string | 'auto' | Sets the maximum height for a scrollable content. |
navigationNextLabel | string | — | Label used for navigation control next button tooltip. |
navigationPreviousLabel | string | — | Label used for navigation control previous button tooltip. |
onAfterClose | () => void | — | Callback that is executed after the modal has been closed. |
onAfterOpen | () => void | — | Callback that is executed after the modal has been opened. |
onNavigationClickNext | () => void | — | Callback that is executed when the navigation control next is clicked. |
onNavigationClickPrevious | () => void | — | Callback that is executed when the navigation control previous is clicked. |
onOk | () => void | — | |
onRequestClose | (event?: KeyboardEvent<Element> | MouseEvent<Element, MouseEvent> | undefined) => void | — | Callback that is executed when the modal is requested to be closed, prior to actually closing. |
overlayPosition | "fixed" | "static" | "sticky" | "relative" | "absolute" | 'fixed' | Controls the CSS position of the modal overlay. |
parentSelector | () => HTMLElement | — | A function that returns a DOM element on which the modal should be appended to. |
ref | null | string | (instance: ModalComponent | null) => void | RefObject<ModalComponent> | — | 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). |
screen | "desktop" | "full" | "mobile" | 'desktop' | Specifies minimum spacing between full viewport and modal content. |
scrollable | boolean | true | Specifies if modal portal supports scroll. |
scrollableContent | boolean | false | Specifies if modal content should become scrollable when the modal is sized to fit the window. |
shouldCloseOnOverlayClick | boolean | false | Enables to close modal when mouse clicked on overlay area. |
shouldDisplayCloseButton | boolean | false | Displays a close button on the top right corner of the overlay. |
showNavigationNextButton | boolean | — | Enable navigation next button to the side of the content and listen on clicks by using onNavigationClickNext. |
showNavigationPreviousButton | boolean | — | Enable navigation previous buttons to the side of the content and listen on clicks by using onNavigationClickPrevious. |
transition | "scale" | "moveHorizontal" | "moveVertical" | scale | Transition animation type. Note that moveHorizontal/moveVertical transitions work best with FullScreenModalLayout. |
verticalPosition | "center" | "end" | "start" | 'center' | Vertical position of the modal. |
zIndex | number | — | Controls z-index of the modal overlay. |
Import the driver matching your test environment:
| Method | Description |
|---|---|
exists | true if the modal is on the DOM |
isOpen | true when the module is open |
getChildBySelector | — |
isScrollable | true if the modal is scrollable |
closeButtonExists | — |
clickOnOverlay | click on the modal overlay (helpful for testing if the modal is dismissed) |
clickOnCloseButton | — |
clickOnNavigationPrevious | click on navigation control previous button |
clickOnNavigationNext | click on navigation control next button |
navigationPreviousExists | — |
navigationNextExists | — |
getNavigationPreviousLabel | — |
getNavigationNextLabel | — |
getContent | returns the element of the modal content (helpful to initialize a layout testkit) |
getContentStyle | returns the style of the modal content |
getContentLabel | returns the modal aria-label value as given in contentLabel property |
getZIndex | — |
element | Gets the component root element. |
click | Clicks on the component root element. |
base | Returns UniDriver for the base element. |
WixDesignSystemProvider has mobile enabled, a focused field inside the modal is now scrolled above the on-screen keyboard instead of being hidden behind it. The same behavior is available for your own scroll containers through the new useKeyboardAwareScroll hook. (#17277)Last updated: 22 October 2026