CustomModalLayout

Components/Overlays/Modal

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

Overview

Copy

Custom modal layouts are highly flexible, allowing to contain content like forms, lists, or media within a <Modal/> overlay.

Do

  • Use it to present a subtask, display more information or other custom content.
  • Use it after an intentional user action and only when it is completely necessary. Because they are intrusive, modals should be used sparingly.

Don't

  • Don't use to display essential information or primary tasks. Use <Card/> on the main page instead.
  • Don't use to prevent users from taking a destructive action or to communicate short messages. Use <MessageModalLayout/> instead.
  • Don't use to preview files such as images, videos or PDFs. Use <ModalPreviewLayout/> instead.
  • Don't use in mobile environments. Use <FullScreenModalLayout/> instead

Feature examples

Structure

The custom modal layout can include the following:

  • title (required)
  • subtitle
  • content (required)
  • sideActions
  • footnote

To 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."

Copy

Height and width

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.

Copy

Content padding

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

Copy

Theme

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

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

Help and close buttons

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.

Copy

Side actions

Add supplementary actions in the sideActions container.

Copy

Footnote

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.

Copy

Title and subtitle

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.

Copy

Action buttons

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.

Copy

Disabled primary action

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.

Copy

Developer examples

Vertical overflow

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.

Copy

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.

Copy

Mobile

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.

Copy

Common use case examples

Remove default content padding when displaying a <Table/>, <Page/> or other content with built-in or custom padding.

Copy

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.

Copy

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.

Copy

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.

Copy

Accessibility examples

Using modals

Users with disabilities have difficulty interacting with modals, so use them sparingly, and only for specific purposes.

  • Use modals to confirm an action, or to perform subtasks that aren't the primary tasks on the page.
  • Don't use modals to save space on a page. Consider using expand/collapse functionality instead.
  • Avoid opening multiple modals one after the other as it can disorient the users. Consider using a separate flow.
Copy

Heading structure

All modals must have a logical, descending heading structure that doesn't skip levels.

  • Use <h2> for the main modal heading.
  • Use <h3> for subsequent headings within the modal.
  • Don't skip heading levels.
Copy

Code

Copy

Props

NameTypeDefaultDescription
actionsSize"small" | "tiny" | "medium" | "large"—Sets the size of action buttons.
childrenReactNode—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.
closeButtonPropsModalCloseButtonProps—Close button props.
contentReactNode—Sets the modal's main content, rendered in the middle scrollable area. When omitted, children are rendered in this area instead.
contentClassNamestring—
dataHookstring—Applies a data-hook HTML attribute to be used in the tests.
footerClassNamestring—
footnoteReactNode—Renders supplementary text or other components at the bottom of the modal.
footnoteClassNamestring—
footnoteSkin"light" | "neutral"—Sets the look and feel of the footnote.
headerClassNamestring—
heightstring | number | string & {}—Fixes the height of component.
helpButtonPropsModalControlButtonProps—Help button props.
illustrationReactNode—
illustrationClassNamestring—
maxHeightstring | number | string & {}—Sets the maximum height of component; if content area is longer than maxHeight, it scrolls vertically.
maxWidthstring | number | string & {}—Sets the maximum width of component; if content area is longer than maxWidth, it scrolls horizontally.
onCloseButtonClickMouseEventHandler—
onHelpButtonClickMouseEventHandler—
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.
primaryButtonPropsOmit<ButtonProps, "internalDataHook">—Passes on any <Button/> properties on the primary button.
primaryButtonTextReactNode—Sets text label or other content (e.g., ) for the primary button.
primaryButtonTooltipPropsTooltipCommonProps & { content: ReactNode; }—Passes on any <Tooltip/> properties on the primary button tooltip.
removeContentPaddingboolean—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.
secondaryButtonPropsOmit<ButtonProps, "internalDataHook">—Passes on any <Button/> properties on the secondary button.
secondaryButtonTextReactNode—Sets text label for the secondary button.
showFooterDividerfalse | 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.
showHeaderDividerfalse | 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.
sideActionsReactNode—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.
styleCSSProperties—Sets object of CSS styles.
subtitleReactNode—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.
titleReactNode—Sets text title for the modal; can be used in conjunction with other components.
widthstring | number | string & {}—Fixes the width of component; if content area is wider than width, it scrolls horizontally.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
hasContentPaddingChecks whether the modal content has padding
getThemeGets the modal theme
getSkinGets the modal skin
clickCloseButtonClicks the modal close-button
clickHelpButtonClicks the modal help-button
childExistsChecks whether a node with the provided dataHook exists
getTitleTextGets the title's text
getSubtitleTextGets the subtitle's text
secondaryButtonDriverGets the secondary button driver
getSecondaryButtonDriverGets the secondary button driver
primaryButtonDriverGets the primary button driver
getPrimaryButtonDriverGets the primary button driver
getPrimaryButtonTooltipContentGets the primary button's tooltip content
getIllustrationSrcGets the illustration source
existsChecks whether the component found with the given data hook.
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.331.0 (2026-10-01) — maintenance release, no component-specific changes
  • 1.330.1 (2026-09-28) — 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.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.308.0 (2026-08-04) — maintenance release, no component-specific changes
  • 1.305.0 (2026-07-28) — fix: align close button with the design [Harmony] (#16623) — has visual 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.273.0 (2026-04-30) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.263.0 (2026-03-31) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.253.0 (2026-01-30) — maintenance release, no component-specific changes
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.235.0 (2025-12-04) — maintenance release, no component-specific changes
  • 1.213.0 (2025-08-19) — breaking: typo fixes and value alignment (#15167)
  • 1.202.0 (2025-06-27) — breaking: tokenization (#15000)
  • 1.196.0 (2025-06-04) — maintenance release, no component-specific changes
  • 1.186.0 (2025-05-05) — maintenance release, no component-specific changes
  • 1.173.0 (2025-03-25) — fix: expose type of style (#14669)
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.106.0 (2024-05-24) — maintenance release, no component-specific changes
  • 1.105.3 (2024-05-23) — fix: add footnoteSkin property to CustomModalLayoutProps (#13766)
  • 1.105.0 (2024-05-21) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.98.0 (2024-03-15) — maintenance release, no component-specific changes
  • 1.93.0 (2024-02-08) — 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?