Overview
Go Headless

Changelog

Wix Design System (WDS)
Introduction
About Wix Design System
Get started developing
Get started designing
Theming
Wix Design System AI

Guidelines
Themes
Interaction & Behavior
Guidelines
Localization

Patterns
Patterns Overview
Table Pattern
Grid Switch Pattern
Grid Pattern

Foundations
Tokens and Theming basics
Icon Theming

Contributing
AI-Assisted Development
Component Structure
Contributing to Wix Design System
Creating a New Component
Creating a Pull Request
Deprecating a Component
Documenting
Fixing a Bug
Test Drivers
Contributing Tokens
Token Migration Guidelines
Updating Props
Writing Tests

Components
Actions
Animations
Charts
Feedback
Form
Layout
Lists
Mechanisms
Media
Navigation
Overlays
Drawer Component
FloatingHelper Component
FullScreenModalLayout
Modal
Modal Component
AnnouncementModalLayout Component
CustomModalLayout Component
MessageModalLayout Component
ModalMobileLayout Component
ModalPreviewLayout Component
Popover Component
PopoverMenu Component
SidePanel Component
Tooltip Component
Panels
Typography
In This Article

  1. Overview
  2. Code
  3. Testkit
  4. Changelog

Modal

Components/Overlays/Modal

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/modal

Overview

Copy

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/>.

Do

  • Use it as the background for all types of modal layouts.
  • Use it only when it is completely necessary. Because they are intrusive, modals should be used sparingly.

Don't

  • Don't use modals without any intentional user action.

Feature examples

Structure

Modal consists of an overlay only and should contain one of the following layouts:

  • <CustomModalLayout/>
  • <ModalPreviewLayout/>
  • <AnnouncementModalLayout/>
  • <ModalMobileLayout/>
Copy

Side margins

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.
Copy

Navigation controls

Add the option to navigate between modals by using the showNavigationPreviousButton and showNavigationNextButton props.

Copy

Common use case examples

Desktop modal with popover elements

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.

Copy

Code

Copy

Props

NameTypeDefaultDescription
appElementstring—Selector specifying where to apply the aria-hidden attribute.
borderRadiusnumber0Border radius of modal.
childrenReactNode—Renders modal content.
closeTimeoutMSnumber500Number indicating the milliseconds to wait before closing the modal.
contentLabelstring—Sets the aria-label of the modal element. It helps assistive technology, like screen readers, to label an element that would otherwise be anonymous.
dataHookstring—Applied as data-hook HTML attribute that can be used to create driver in testing.
heightstring'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.
maxHeightstring'auto'Sets the maximum height for a scrollable content.
navigationNextLabelstring—Label used for navigation control next button tooltip.
navigationPreviousLabelstring—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.
refnull | 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.
scrollablebooleantrueSpecifies if modal portal supports scroll.
scrollableContentbooleanfalseSpecifies if modal content should become scrollable when the modal is sized to fit the window.
shouldCloseOnOverlayClickbooleanfalseEnables to close modal when mouse clicked on overlay area.
shouldDisplayCloseButtonbooleanfalseDisplays a close button on the top right corner of the overlay.
showNavigationNextButtonboolean—Enable navigation next button to the side of the content and listen on clicks by using onNavigationClickNext.
showNavigationPreviousButtonboolean—Enable navigation previous buttons to the side of the content and listen on clicks by using onNavigationClickPrevious.
transition"scale" | "moveHorizontal" | "moveVertical"scaleTransition animation type. Note that moveHorizontal/moveVertical transitions work best with FullScreenModalLayout.
verticalPosition"center" | "end" | "start"'center'Vertical position of the modal.
zIndexnumber—Controls z-index of the modal overlay.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
existstrue if the modal is on the DOM
isOpentrue when the module is open
getChildBySelector—
isScrollabletrue if the modal is scrollable
closeButtonExists—
clickOnOverlayclick on the modal overlay (helpful for testing if the modal is dismissed)
clickOnCloseButton—
clickOnNavigationPreviousclick on navigation control previous button
clickOnNavigationNextclick on navigation control next button
navigationPreviousExists—
navigationNextExists—
getNavigationPreviousLabel—
getNavigationNextLabel—
getContentreturns the element of the modal content (helpful to initialize a layout testkit)
getContentStylereturns the style of the modal content
getContentLabelreturns the modal aria-label value as given in contentLabel property
getZIndex—
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.332.0 (2026-10-05) — feat: set shared default props through WixDesignSystemDefaultPropsProvider. (#17340)
  • 1.331.0 (2026-10-01) — feat: when 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)
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.324.0 (2026-09-14) — maintenance release, no component-specific changes
  • 1.322.0 (2026-09-09) — maintenance release, no component-specific changes
  • 1.321.0 (2026-09-08) — fix: every modal layout now renders the border defined by the theme, so modals stay visible against same-colored page backgrounds. (#16806)
  • 1.320.1 (2026-09-04) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.278.0 (2026-05-08) — maintenance release, no component-specific changes
  • 1.270.0 (2026-04-20) — fix: fixed issue with safari and naviagtion with tab/shifttab (#16131)
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — fix: add safe default parent selector (#16012)
  • 1.254.0 (2026-02-03) — maintenance release, no component-specific changes
  • 1.252.0 (2026-01-28) — fix: made trigger element stay in focus if modal is closed (#15872)
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.247.0 (2026-01-13) — maintenance release, no component-specific changes
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.234.0 (2025-12-03) — fix: when Modal opened on top of Drawer fix (#15615)
  • 1.232.0 (2025-11-28) — fix: make shadow-surface-modal responsive (#15543)
  • 1.228.0 (2025-11-18) — maintenance release, no component-specific changes
  • 1.225.0 (2025-11-07) — feat: add transition animations (#15466)
  • 1.212.0 (2025-08-11) — feat: blur backdrop (#15172)
  • 1.203.0 (2025-07-01) — breaking: tokenization (#15010)
  • 1.200.0 (2025-06-17) — maintenance release, no component-specific changes
  • 1.169.0 (2025-03-10) — maintenance release, no component-specific changes
  • 1.165.0 (2025-02-27) — maintenance release, no component-specific changes
  • 1.156.0 (2025-01-29) — fix: removed throw when checking if modal doesn't exist (#14491)
  • 1.155.0 (2025-01-23) — maintenance release, no component-specific changes
  • 1.154.0 (2025-01-17) — maintenance release, no component-specific changes
  • 1.144.0 (2024-12-03) — maintenance release, no component-specific changes
  • 1.143.0 (2024-11-25) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?