Components/Overlays/Modal
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/custommodallayout
Custom modal layouts are highly flexible, allowing to contain content like forms, lists, or media within a <Modal/> overlay.
<Card/> on the main page instead.<MessageModalLayout/> instead.<ModalPreviewLayout/> instead.<FullScreenModalLayout/> insteadThe custom modal layout can include the following:
title (required)subtitlecontent (required)sideActionsfootnoteTo add supplementary actions, like a "Don't show this again" checkbox, use sideActions.
To include additional information, add a footnote, e.g., "By sending an invite, you agree to the Wix Terms of Use."
By default, modals grow with their content, but they'll never extend higher than the user's viewport (with 48 px top and bottom padding).
Control a custom modal's height with these two properties:
height fixes height in pixels.maxHeight sets a custom max height in pixels.When modal content extends below the user's viewport, height or maxHeight, content scrolls vertically with a fixed header and footer.
Control a custom modal's width with width property.
Minimum width of a modal is 510px., maximum width is 1254px.
Remove the default 30 px left and right content padding with the removeContentPadding prop.
This property can be used to show components with built-in padding like <Page/> or <Table/>.
Control the component style with theme prop:
standard is the default used in all common cases.premium is used to promote Premium features.destructive is for actions that have a destructive effect on user data, like delete. For short warning messages, use the <MessageModalLayout/> in a destructive theme instead.Control visibility of both the header and footer dividers with the showHeaderDivider and showFooterDivider props.
auto is the default that shows header divider only when content is scrolled and always shows the footer divider.true always shows the dividers.false always hides the dividers.Add a help button with the onHelpButtonClick prop. Use it to direct users to support sources, for example, the Wix Help Center.
The close button is required for all modals.
Add supplementary actions in the sideActions container.
Add supplementary text and links into the footnote container.
Footnote also has a footnoteSkin property, that provides a light skin, that can be used fore busier modal layouts.
Add short text to summarize modal content with the title and subtitle props.
Both title and subtitle are nodes, so they can contain other components. For example, add inline <TextButton/> linking to relevant information in a subtitle.
Specify labels for primary and secondary actions with primaryButtonText and secondaryButtonText props.
For additional styling, like adding a prefix icon, use any available <Button/> props via the primaryButtonProps and secondaryButtonProps.
Disable a primary action using the disabled prop in primaryButtonProps.
Add an explanation in a tooltip about why this action is not allowed with primaryButtonTooltipProps.
Use any of the <Tooltip/> props to style the tooltip.
Modal headers and footers can cut content outlines when placed next to the top or bottom content areas.
Set vertical overflowY prop to none to show the full outline.
By default, modals do not allow content to overflow.
Use popoverProps, appendTo and dynamicWidth props to display overlays as intended. For more guidance, read about the <Popover/> component.
On mobile CustomModalLayout maps to FullScreenModalLayout for cases where complex or multi-step flows are included
If the layout is simple, short, up to one step - use Drawer
To see the change, toggle 'Enable mobile support' in the top bar of Storybook.
Remove default content padding when displaying a <Table/>, <Page/> or other content with built-in or custom padding.
If a modal has more than two actions, use sideActions container to group them.
Cancel button is required and should always be positioned on the left side of the action list.
When a <Page/> can be accessed from multiple entry points, show it in a modal to keep users in the main flow.
Make the modal as large as possible and structure content within cards. If other modals can be triggered, make them significantly smaller to communicate their hierarchy.
Focus users' attention on feature promotions with modals. Use them sparingly and only after users intentionally open the promotional content.
For example, use a custom modal layout with a <MarketingLayout/> inside.
Users with disabilities have difficulty interacting with modals, so use them sparingly, and only for specific purposes.
All modals must have a logical, descending heading structure that doesn't skip levels.
<h2> for the main modal heading.<h3> for subsequent headings within the modal.| Name | Type | Default | Description |
|---|---|---|---|
actionsSize | "small" | "tiny" | "medium" | "large" | — | Sets the size of action buttons. |
children | ReactNode | — | Sets the modal's content. Rendered in the middle scrollable area when content is omitted; when content is provided, rendered directly inside the modal root after the layout blocks, so fully custom nodes can be mounted and animated. |
closeButtonProps | ModalCloseButtonProps | — | Close button props. |
content | ReactNode | — | Sets the modal's main content, rendered in the middle scrollable area. When omitted, children are rendered in this area instead. |
contentClassName | string | — | |
dataHook | string | — | Applies a data-hook HTML attribute to be used in the tests. |
footerClassName | string | — | |
footnote | ReactNode | — | Renders supplementary text or other components at the bottom of the modal. |
footnoteClassName | string | — | |
footnoteSkin | "light" | "neutral" | — | Sets the look and feel of the footnote. |
headerClassName | string | — | |
height | string | number | string & {} | — | Fixes the height of component. |
helpButtonProps | ModalControlButtonProps | — | Help button props. |
illustration | ReactNode | — | |
illustrationClassName | string | — | |
maxHeight | string | number | string & {} | — | Sets the maximum height of component; if content area is longer than maxHeight, it scrolls vertically. |
maxWidth | string | number | string & {} | — | Sets the maximum width of component; if content area is longer than maxWidth, it scrolls horizontally. |
onCloseButtonClick | MouseEventHandler | — | |
onHelpButtonClick | MouseEventHandler | — | |
overflowY | "visible" | "hidden" | "none" | "clip" | "-moz-initial" | "inherit" | "initial" | "revert" | "revert-layer" | "unset" | "auto" | "scroll" | "-moz-hidden-unscrollable" | — | Determines what happens when content overflows component vertically. Value 'none' will be removed in next major, use "visible" value instead. |
primaryButtonOnClick | () => void | — | Defines a call-back function after user clicks on the primary button. |
primaryButtonProps | Omit<ButtonProps, "internalDataHook"> | — | Passes on any <Button/> properties on the primary button. |
primaryButtonText | ReactNode | — | Sets text label or other content (e.g., |
primaryButtonTooltipProps | TooltipCommonProps & { content: ReactNode; } | — | Passes on any <Tooltip/> properties on the primary button tooltip. |
removeContentPadding | boolean | — | Removes 30 px left and right padding from the content area. |
secondaryButtonOnClick | () => void | — | Defines a call-back function after user clicks on the secondary button. |
secondaryButtonProps | Omit<ButtonProps, "internalDataHook"> | — | Passes on any <Button/> properties on the secondary button. |
secondaryButtonText | ReactNode | — | Sets text label for the secondary button. |
showFooterDivider | false | true | "auto" | — | Controls visibility of a footer divider. When set to auto, it is shown up until content is scrolled to the very bottom. When set to true, it is always visible, and when set to false, it is always hidden. |
showHeaderDivider | false | true | "auto" | — | Controls visibility of a header divider. When set to auto, it is shown only when scroll position is greater than 0. When set to true, it is always visible, and when set to false, it is always hidden. |
sideActions | ReactNode | — | Contains a checkbox or other components at the start of the footer. |
skin | "standard" | "destructive" | "premium" | — | a global skin for the modal, will affect footer buttons skin. |
style | CSSProperties | — | Sets object of CSS styles. |
subtitle | ReactNode | — | Sets text subtitle for the modal; can be used in conjunction with other components. |
theme | "standard" | "destructive" | "premium" | — | Controls the skin of the modal. It's ignored when skin is provided. |
title | ReactNode | — | Sets text title for the modal; can be used in conjunction with other components. |
width | string | number | string & {} | — | Fixes the width of component; if content area is wider than width, it scrolls horizontally. |
Import the driver matching your test environment:
| Method | Description |
|---|---|
hasContentPadding | Checks whether the modal content has padding |
getTheme | Gets the modal theme |
getSkin | Gets the modal skin |
clickCloseButton | Clicks the modal close-button |
clickHelpButton | Clicks the modal help-button |
childExists | Checks whether a node with the provided dataHook exists |
getTitleText | Gets the title's text |
getSubtitleText | Gets the subtitle's text |
secondaryButtonDriver | Gets the secondary button driver |
getSecondaryButtonDriver | Gets the secondary button driver |
primaryButtonDriver | Gets the primary button driver |
getPrimaryButtonDriver | Gets the primary button driver |
getPrimaryButtonTooltipContent | Gets the primary button's tooltip content |
getIllustrationSrc | Gets the illustration source |
exists | Checks whether the component found with the given data hook. |
element | Gets the component root element. |
click | Clicks on the component root element. |
base | Returns UniDriver for the base element. |
style (#14669)Last updated: 22 October 2026