> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: CustomModalLayout Component

## Article: CustomModalLayout Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/overlays/modal/custom-modal-layout-component.md

## Article Content:

# CustomModalLayout

_Components/Overlays/Modal_

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

## Overview

```jsx
<Box align="center">
  <CustomModalLayout
    showFooterDivider
    primaryButtonText="Apply"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Apply a coupon"
    content={<Box height="300px" />}
    width="60%"
  />
</Box>;
```

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

```jsx
<CustomModalLayout
  primaryButtonText="Save"
  secondaryButtonText="Cancel"
  onCloseButtonClick={() => {}}
  title="Title"
  subtitle="Subtitle"
  footnote={
    <StorybookComponents.Placeholder>Footnote</StorybookComponents.Placeholder>
  }
  sideActions={
    <StorybookComponents.Placeholder>
      Side actions
    </StorybookComponents.Placeholder>
  }
  content={
    <StorybookComponents.Placeholder height="240px">
      Content
    </StorybookComponents.Placeholder>
  }
/>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <CustomModalLayout
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    secondaryButtonOnClick={() => {}}
    primaryButtonOnClick={() => {}}
    title="Auto height (default)"
    content={<Box height="180px" />}
  />

  <CustomModalLayout
    height="360px"
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    secondaryButtonOnClick={() => {}}
    primaryButtonOnClick={() => {}}
    title="Height is fixed at 360 px"
    content={<Box height="360px" />}
  />
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <CustomModalLayout
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Default content padding"
    content={<StorybookComponents.Placeholder height="60px" />}
  />
  <CustomModalLayout
    removeContentPadding
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="No content padding"
    content={<StorybookComponents.Placeholder height="60px" />}
  />
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <CustomModalLayout
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Standard (default)"
    content={<StorybookComponents.Placeholder height="60px" />}
  />
  <CustomModalLayout
    theme="premium"
    primaryButtonText="Upgrade"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Premium"
    content={<StorybookComponents.Placeholder height="60px" />}
  />
  <CustomModalLayout
    theme="destructive"
    primaryButtonText="Delete"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Destructive"
    content={<StorybookComponents.Placeholder height="60px" />}
  />
</StorybookComponents.Stack>;
```

#### Header and footer dividers

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.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <CustomModalLayout
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Auto (default)"
    height="240px"
    content={<StorybookComponents.Placeholder height="300px" />}
  />
  <CustomModalLayout
    showFooterDivider
    showHeaderDivider
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Always show dividers"
    height="240px"
    content={<StorybookComponents.Placeholder height="300px" />}
  />
  <CustomModalLayout
    showFooterDivider={false}
    showHeaderDivider={false}
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Hide dividers"
    height="240px"
    content={<StorybookComponents.Placeholder height="300px" />}
  />
</StorybookComponents.Stack>;
```

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

```jsx
<CustomModalLayout
  primaryButtonText="Save"
  secondaryButtonText="Cancel"
  onCloseButtonClick={() => {}}
  onHelpButtonClick={() => {}}
  title="Title"
  content={<StorybookComponents.Placeholder height="60px" />}
/>;
```

#### Side actions

Add supplementary actions in the `sideActions` container.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <CustomModalLayout
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Title"
    sideActions={
      <StorybookComponents.Placeholder>
        Side actions
      </StorybookComponents.Placeholder>
    }
    content={<StorybookComponents.Placeholder height="60px" />}
  />
  <CustomModalLayout
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Title"
    sideActions={<Checkbox>Don’t show this again</Checkbox>}
    content={<StorybookComponents.Placeholder height="60px" />}
  />
  <CustomModalLayout
    onCloseButtonClick={() => {}}
    title="Title"
    sideActions={
      <StorybookComponents.Stack justifyContent="space-between">
        <Button priority="secondary" size="small">
          Cancel
        </Button>
        <StorybookComponents.Stack gap="8px" justifyContent="flex-end">
          <Button
            priority="secondary"
            size="small"
            prefixIcon={<Icons.DismissSmall />}
          >
            Reject
          </Button>
          <Button
            priority="secondary"
            size="small"
            prefixIcon={<Icons.TimeSmall />}
          >
            Keep for later
          </Button>
          <Button
            priority="secondary"
            size="small"
            prefixIcon={<Icons.ConfirmSmall />}
          >
            Approve
          </Button>
        </StorybookComponents.Stack>
      </StorybookComponents.Stack>
    }
    content={<StorybookComponents.Placeholder height="60px" />}
  />
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <CustomModalLayout
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Title"
    footnote={
      <StorybookComponents.Placeholder>
        Footnote
      </StorybookComponents.Placeholder>
    }
    content={<StorybookComponents.Placeholder height="60px" />}
  />

  <CustomModalLayout
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Title"
    footnote={
      <Text size="small">
        By continuing, you agree to the <a>Wix Terms of Use</a>
      </Text>
    }
    content={<StorybookComponents.Placeholder height="60px" />}
  />
  <CustomModalLayout
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Title"
    footnoteSkin="light"
    footnote={
      <Text size="small">
        By continuing, you agree to the <a>Wix Terms of Use</a>
      </Text>
    }
    content={<StorybookComponents.Placeholder height="60px" />}
  />
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <CustomModalLayout
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Title (required)"
    subtitle="Subtitle (optional)"
    content={<StorybookComponents.Placeholder height="60px" />}
  />
  <CustomModalLayout
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Title"
    subtitle={
      <StorybookComponents.Stack gap="6px">
        <Text secondary>Subtitle</Text>
        <TextButton underline="always">Inline text button</TextButton>
      </StorybookComponents.Stack>
    }
    content={<StorybookComponents.Placeholder height="60px" />}
  />
</StorybookComponents.Stack>;
```

#### 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/>`](https://wix-pages.com/design-system-documentation/#/component/button) props via the `primaryButtonProps` and `secondaryButtonProps`.

```jsx
<CustomModalLayout
  primaryButtonText="Approve"
  primaryButtonProps={{ prefixIcon: <Icons.ConfirmSmall /> }}
  secondaryButtonText="Reject"
  secondaryButtonProps={{ prefixIcon: <Icons.DismissSmall /> }}
  onCloseButtonClick={() => {}}
  title="Title"
  content={<StorybookComponents.Placeholder height="60px" />}
/>;
```

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

```jsx
<CustomModalLayout
  primaryButtonText="Save"
  primaryButtonProps={{ disabled: true }}
  primaryButtonTooltipProps={{ content: 'Tells users why they cannot Save' }}
  secondaryButtonText="Cancel"
  onCloseButtonClick={() => {}}
  title="Title"
  content={<StorybookComponents.Placeholder height="60px" />}
/>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <CustomModalLayout
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Title"
    content={<Input placeholder="Click here to see the default outlines" />}
  />
  <CustomModalLayout
    primaryButtonText="Save"
    secondaryButtonText="Cancel"
    onCloseButtonClick={() => {}}
    title="Title"
    overflowY="none"
    content={
      <Input placeholder="Click here to see the outlines with overflowY prop" />
    }
  />
</StorybookComponents.Stack>;
```

#### Modal with overlays

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.

```jsx
() => {
  const [shown, setShown] = React.useState(false);

  return (
    <Card>
      <Card.Header
        title="Allow using coupons"
        subtitle="Let visitors use coupons to get discounts & special deals."
        suffix={
          <Button
            size="small"
            priority="secondary"
            onClick={() => setShown(true)}
          >
            Apply Coupon
          </Button>
        }
      />
      <Modal
        isOpen={shown}
        onRequestClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        screen="desktop"
      >
        <CustomModalLayout
          primaryButtonText="Apply"
          primaryButtonOnClick={() => setShown(false)}
          secondaryButtonText="Cancel"
          secondaryButtonOnClick={() => setShown(false)}
          onCloseButtonClick={() => setShown(false)}
          title="Apply a coupon"
          overflowY="none"
          content={
            <FormField label="Select coupon">
              <Dropdown
                popoverProps={{
                  appendTo: 'scrollParent',
                  dynamicWidth: true,
                }}
                options={[
                  { id: 0, value: 'None' },
                  { id: 1, value: 'SUMMER15' },
                  { id: 2, value: 'BACKTOSCHOOL' },
                  { id: 3, value: 'AUGUST10' },
                  { id: 4, value: 'OUTWITHTHEOLD' },
                ]}
                placeholder="Select from the list"
              />
            </FormField>
          }
        />
      </Modal>
    </Card>
  );
};
```

#### 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._

```jsx
() => {
  const [complexOpen, setComplexOpen] = React.useState(false);
  const [simpleOpen, setSimpleOpen] = React.useState(false);
  const [step, setStep] = React.useState(1);
  const { mobile } = React.useContext(WixDesignSystemContext);

  // Complex form state
  const [projectName, setProjectName] = React.useState('');
  const [category, setCategory] = React.useState(null);
  const [template, setTemplate] = React.useState('starter');
  const [visibility, setVisibility] = React.useState('public');
  const [features, setFeatures] = React.useState({
    comments: false,
    seo: true,
    analytics: false,
  });
  const [notifications, setNotifications] = React.useState(true);
  const [agreed, setAgreed] = React.useState(false);

  // Simple form state
  const [tagName, setTagName] = React.useState('');
  const [tagColor, setTagColor] = React.useState('blue');
  const [pinned, setPinned] = React.useState(false);

  const categoryOptions = [
    { id: 'blog', value: 'blog', label: 'Blog' },
    { id: 'portfolio', value: 'portfolio', label: 'Portfolio' },
    { id: 'ecommerce', value: 'ecommerce', label: 'E-Commerce' },
    { id: 'docs', value: 'docs', label: 'Documentation' },
  ];

  const toggleFeature = (key) => (e) =>
    setFeatures((f) => ({ ...f, [key]: e.target.checked }));

  const stepTitles = {
    1: 'Project Setup',
    2: 'Configuration',
    3: 'Review & Confirm',
  };

  const SummaryRow = ({ label, value }) => (
    <Box align="space-between" verticalAlign="middle" gap="SP4">
      <Text size="small" style={{ flexShrink: 0 }}>
        {label}
      </Text>
      <Text size="small" align="right">
        {value}
      </Text>
    </Box>
  );

  const stepContent = {
    1: (
      <Box direction="vertical" gap="SP4">
        <FormField label="Project name" required>
          <Input
            placeholder="My awesome project"
            value={projectName}
            onChange={(e) => setProjectName(e.target.value)}
          />
        </FormField>
        <FormField label="Category">
          <Dropdown
            placeholder="Select a category"
            options={categoryOptions}
            selectedId={category}
            onSelect={(opt) => setCategory(opt.id)}
          />
        </FormField>
        <FormField label="Start from">
          <RadioGroup
            value={template}
            onChange={(value) => setTemplate(String(value))}
          >
            <RadioGroup.Radio value="blank">
              Blank — start from scratch
            </RadioGroup.Radio>
            <RadioGroup.Radio value="starter">
              Starter template — basic structure included
            </RadioGroup.Radio>
            <RadioGroup.Radio value="advanced">
              Advanced template — full setup with sample content
            </RadioGroup.Radio>
          </RadioGroup>
        </FormField>
      </Box>
    ),
    2: (
      <Box direction="vertical" gap="SP4" width="100%">
        <FormField label="Visibility">
          <RadioGroup
            value={visibility}
            onChange={(value) => setVisibility(String(value))}
          >
            <RadioGroup.Radio value="public">
              Public — anyone can view
            </RadioGroup.Radio>
            <RadioGroup.Radio value="private">
              Private — only you
            </RadioGroup.Radio>
            <RadioGroup.Radio value="team">Team — invite only</RadioGroup.Radio>
          </RadioGroup>
        </FormField>
        <Divider />
        <FormField label="Enable features">
          <Box direction="vertical" gap="SP2">
            <Checkbox
              checked={features.comments}
              onChange={toggleFeature('comments')}
            >
              Comments
            </Checkbox>
            <Checkbox checked={features.seo} onChange={toggleFeature('seo')}>
              SEO optimization
            </Checkbox>
            <Checkbox
              checked={features.analytics}
              onChange={toggleFeature('analytics')}
            >
              Analytics dashboard
            </Checkbox>
          </Box>
        </FormField>
        <Divider />
        <Box align="space-between" verticalAlign="middle">
          <Box direction="vertical">
            <Text weight="normal">Email notifications</Text>
            <Text size="tiny" secondary>
              Get updates on project activity
            </Text>
          </Box>
          <ToggleSwitch
            checked={notifications}
            onChange={(e) => setNotifications(e.target.checked)}
          />
        </Box>
      </Box>
    ),
    3: (
      <Box direction="vertical" width="100%" gap="SP4">
        <Box width="100%" direction="vertical" gap="SP3">
          <SummaryRow label="Name" value={projectName || '—'} />
          <SummaryRow
            label="Category"
            value={categoryOptions.find((o) => o.id === category)?.label || '—'}
          />
          <SummaryRow label="Template" value={template} />
          <Divider />
          <SummaryRow label="Visibility" value={visibility} />
          <SummaryRow
            label="Features"
            value={
              Object.entries(features)
                .filter(([, v]) => v)
                .map(([k]) => k)
                .join(', ') || 'None'
            }
          />
          <SummaryRow
            label="Notifications"
            value={notifications ? 'On' : 'Off'}
          />
        </Box>
        <Checkbox
          checked={agreed}
          onChange={(e) => setAgreed(e.target.checked)}
        >
          I agree to the terms and conditions
        </Checkbox>
      </Box>
    ),
  };

  const openComplex = () => {
    setStep(1);
    setComplexOpen(true);
  };
  const closeComplex = () => setComplexOpen(false);
  const next = () => (step < 3 ? setStep(step + 1) : closeComplex());
  const back = () => setStep(step - 1);
  const isNextDisabled = step === 3 && !agreed;

  const closeSimple = () => setSimpleOpen(false);

  const simpleContent = (
    <Box direction="vertical" gap="SP4">
      <FormField label="Tag name" required>
        <Input
          placeholder="e.g. Urgent"
          value={tagName}
          onChange={(e) => setTagName(e.target.value)}
        />
      </FormField>
      <FormField label="Color">
        <RadioGroup
          value={tagColor}
          onChange={(value) => setTagColor(String(value))}
        >
          <RadioGroup.Radio value="blue">Blue</RadioGroup.Radio>
          <RadioGroup.Radio value="green">Green</RadioGroup.Radio>
          <RadioGroup.Radio value="red">Red</RadioGroup.Radio>
        </RadioGroup>
      </FormField>
      <Checkbox checked={pinned} onChange={(e) => setPinned(e.target.checked)}>
        Pin to top
      </Checkbox>
    </Box>
  );

  return (
    <Box padding="20px" gap="SP3">
      <Button onClick={openComplex}>Complex form</Button>
      <Button priority="secondary" onClick={() => setSimpleOpen(true)}>
        Simple form
      </Button>

      {/* Complex form — FullScreenModalLayout on mobile, CustomModalLayout on desktop */}
      {mobile ? (
        <Modal
          isOpen={complexOpen}
          onRequestClose={closeComplex}
          screen="mobile"
        >
          <FullScreenModalLayout>
            <FullScreenModalLayout.Header
              startNode={
                <CloseButton skin="dark" size="large" onClick={closeComplex} />
              }
            >
              <Text>Step {step} of 3</Text>
            </FullScreenModalLayout.Header>
            <FullScreenModalLayout.Content padding>
              <Box direction="vertical" gap="SP4">
                <Heading size="small">{stepTitles[step]}</Heading>
                {stepContent[step]}
              </Box>
            </FullScreenModalLayout.Content>
            <FullScreenModalLayout.Footer>
              <Box direction="horizontal" width="100%" gap="SP2" padding="SP4">
                {step > 1 ? (
                  <Button priority="secondary" onClick={back} fullWidth>
                    Back
                  </Button>
                ) : (
                  <Button priority="secondary" onClick={closeComplex} fullWidth>
                    Cancel
                  </Button>
                )}
                <Button onClick={next} fullWidth>
                  {step < 3 ? 'Next' : 'Finish'}
                </Button>
              </Box>
            </FullScreenModalLayout.Footer>
          </FullScreenModalLayout>
        </Modal>
      ) : (
        <Modal isOpen={complexOpen} onRequestClose={closeComplex}>
          <CustomModalLayout
            width="600px"
            title={stepTitles[step]}
            subtitle={`Step ${step} of 3`}
            content={<Box paddingBottom="12px">{stepContent[step]}</Box>}
            primaryButtonText={step < 3 ? 'Next' : 'Finish'}
            primaryButtonOnClick={next}
            primaryButtonProps={{ disabled: isNextDisabled }}
            secondaryButtonText={step > 1 ? 'Back' : undefined}
            secondaryButtonOnClick={step > 1 ? back : undefined}
            onCloseButtonClick={closeComplex}
          />
        </Modal>
      )}

      {/* Simple form — Drawer on mobile, CustomModalLayout on desktop */}
      {mobile ? (
        <Drawer open={simpleOpen} onClose={closeSimple}>
          <Box direction="vertical" gap="SP4" padding="SP5">
            <Heading size="small">Create tag</Heading>
            {simpleContent}
            <Box gap="SP2">
              <Button priority="secondary" onClick={closeSimple} fullWidth>
                Cancel
              </Button>
              <Button onClick={closeSimple} fullWidth>
                Create
              </Button>
            </Box>
          </Box>
        </Drawer>
      ) : (
        <Modal isOpen={simpleOpen} onRequestClose={closeSimple}>
          <CustomModalLayout
            title="Create tag"
            content={<Box paddingBottom="12px">{simpleContent}</Box>}
            primaryButtonText="Create"
            primaryButtonOnClick={closeSimple}
            secondaryButtonText="Cancel"
            secondaryButtonOnClick={closeSimple}
            onCloseButtonClick={closeSimple}
          />
        </Modal>
      )}
    </Box>
  );
};
```

### Common use case examples

#### Modal with no content padding

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

```jsx
() => {
  const [shown, setShown] = React.useState(false);
  const [copy, setCopy] = React.useState(false);

  const data = [
    { name: 'User 1', plan: 'Gold', email: 'user1@mail.com' },
    { name: 'User 2', plan: 'Silver', email: 'user2@mail.com' },
    { name: 'User 3', plan: 'Gold', email: 'user3@mail.com' },
    { name: 'User 4', plan: 'Gold', email: 'user4@mail.com' },
    { name: 'User 5', plan: 'Bronze', email: 'user5@mail.com' },
    { name: 'User 6', plan: 'Bronze', email: 'user6@mail.com' },
    { name: 'User 7', plan: 'Gold', email: 'user7@mail.com' },
    { name: 'User 8', plan: 'Bronze', email: 'user8@mail.com' },
  ];
  const columns = [
    { title: 'Name', render: (row) => row.name },
    { title: 'Plan', render: (row) => row.plan },
    { title: 'Email', render: (row) => row.email },
  ];

  return (
    <Card>
      <Card.Header
        title="Send coupons to your members"
        subtitle="Select members who will receive a new coupon via email."
        suffix={
          <Button
            size="small"
            priority="secondary"
            onClick={() => setShown(true)}
          >
            Send Coupons
          </Button>
        }
      />
      <Modal
        isOpen={shown}
        onRequestClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        screen="desktop"
      >
        <CustomModalLayout
          title="Send coupons to members"
          subtitle="Select members who will receive coupons via email."
          onCloseButtonClick={() => setShown(false)}
          primaryButtonOnClick={() => setShown(false)}
          secondaryButtonOnClick={() => setShown(false)}
          width="720px"
          maxHeight="480px"
          removeContentPadding
          primaryButtonText="Send"
          secondaryButtonText="Cancel"
          sideActions={
            <Checkbox
              size="small"
              checked={copy}
              onChange={() => setCopy(!copy)}
            >
              Send copy Email to myself
            </Checkbox>
          }
          content={
            <Table data={data} columns={columns} showSelection>
              <Table.Content />
            </Table>
          }
        />
      </Modal>
    </Card>
  );
};
```

#### Modal with multiple actions

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.

```jsx
() => {
  const [shown, setShown] = React.useState(false);

  return (
    <Layout>
      <Cell span={6}>
        <Card>
          <Box
            direction="vertical"
            gap="1"
            paddingTop="2"
            paddingLeft="4"
            paddingRight="4"
            paddingBottom="2"
          >
            <Text secondary>From name:</Text>
            <Text weight="bold">User 1</Text>
            <Text secondary>Reply-to email:</Text>
            <Text weight="bold">User1@mail.com</Text>
          </Box>
          <Divider />
          <Box
            paddingTop="2"
            paddingLeft="4"
            paddingRight="4"
            paddingBottom="2"
            align="center"
          >
            <TextButton onClick={() => setShown(true)}>
              Confirm Email
            </TextButton>
          </Box>
          <Modal
            isOpen={shown}
            onRequestClose={() => setShown(false)}
            shouldCloseOnOverlayClick
            screen="desktop"
          >
            <CustomModalLayout
              primaryButtonText="Confirm"
              secondaryButtonText="Change Details"
              onCloseButtonClick={() => setShown(false)}
              secondaryButtonOnClick={() => setShown(false)}
              primaryButtonOnClick={() => setShown(false)}
              overflowY="none"
              width="600px"
              title="Confirm your email address"
              content={
                <Layout>
                  <Cell>
                    <Text>
                      To make changes to your sender details, please confirm
                      your email address.
                      <br />A confirmation code was sent to{' '}
                      <b>user1@mail.com</b>.
                    </Text>
                  </Cell>
                  <Cell span={6}>
                    <FormField label="Confirmation Code">
                      <Input placeholder="XX-XXX-XX" />
                    </FormField>
                  </Cell>
                  <Cell>
                    <Text>
                      Didn't get the code? <a>Send again</a>
                    </Text>
                  </Cell>
                </Layout>
              }
              sideActions={
                <Button
                  onClick={() => setShown(false)}
                  priority="secondary"
                  size="small"
                >
                  Cancel
                </Button>
              }
            />
          </Modal>
        </Card>
      </Cell>
    </Layout>
  );
};
```

#### Modal with a page inside

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.

```jsx
() => {
  const [shown, setShown] = React.useState(false);

  return (
    <Card>
      <Card.Header
        title="Pricing plans"
        subtitle="Let clients book this service with a plan."
        suffix={
          <Button
            size="small"
            priority="secondary"
            prefixIcon={<Icons.AddSmall />}
            onClick={() => setShown(true)}
          >
            Create New Plan
          </Button>
        }
      />
      <Modal
        isOpen={shown}
        onRequestClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        screen="desktop"
      >
        <CustomModalLayout
          primaryButtonText="Create Plan"
          secondaryButtonText="Cancel"
          onCloseButtonClick={() => setShown(false)}
          onHelpButtonClick={() => {}}
          secondaryButtonOnClick={() => setShown(false)}
          primaryButtonOnClick={() => setShown(false)}
          removeContentPadding
          title="Create new pricing plan"
          content={
            <Page>
              <Page.Content>
                <Box marginTop={5} display="block">
                  <Layout>
                    <Cell span={12}>
                      <Card>
                        <Card.Header
                          title="Plan info"
                          subtitle="Give your plan a name and tell customers what it includes"
                        />
                        <Card.Divider />
                        <Card.Content>
                          <Layout>
                            <Cell span={6}>
                              <FormField
                                label="Name this plan"
                                required
                                charCount={20}
                              >
                                <Input placeholder="e.g., Silver Membership" />
                              </FormField>
                            </Cell>
                            <Cell span={6}>
                              <FormField label="Add a tagline" charCount={60}>
                                <Input placeholder="e.g., Perfect for beginners" />
                              </FormField>
                            </Cell>
                            <Cell span={12}>
                              <AddItem size="tiny">
                                Add what this plan includes
                              </AddItem>
                            </Cell>
                          </Layout>
                        </Card.Content>
                      </Card>
                    </Cell>
                    <Cell span={12}>
                      <Card>
                        <Card.Header
                          title="Connect and manage benefits"
                          subtitle="Set up how your benefits work in this plan."
                        />
                        <Card.Divider />
                        <Box
                          display="block"
                          borderRadius={8}
                          paddingBottom="8px"
                        >
                          <SelectableAccordion
                            type="checkbox"
                            items={[
                              {
                                title: 'Bookings Services',
                                subtitle:
                                  'Offer services as a membership or package with this plan.',
                                content: (
                                  <StorybookComponents.Placeholder>
                                    Booking Services content
                                  </StorybookComponents.Placeholder>
                                ),
                              },
                              {
                                title: 'Video Channels',
                                subtitle:
                                  'Offer access to your Video Channel with this plan.',
                                content: (
                                  <StorybookComponents.Placeholder>
                                    Video Channels content
                                  </StorybookComponents.Placeholder>
                                ),
                              },
                              {
                                title: 'Blog Subscriptions',
                                subtitle: 'Give exclusive access to posts.',
                                content: (
                                  <StorybookComponents.Placeholder>
                                    Blog Subscriptions content
                                  </StorybookComponents.Placeholder>
                                ),
                              },
                              {
                                title: 'Forum Subscriptions',
                                subtitle:
                                  'Give exclusive access to forum categories.',
                                content: (
                                  <StorybookComponents.Placeholder>
                                    Forum Subscriptions content
                                  </StorybookComponents.Placeholder>
                                ),
                              },
                              {
                                title: 'Events Memberships',
                                subtitle:
                                  'Add ticket discount and ticket limit for your events.',
                                content: (
                                  <StorybookComponents.Placeholder>
                                    Events Memberships content
                                  </StorybookComponents.Placeholder>
                                ),
                              },
                              {
                                title: 'Online Programs',
                                subtitle:
                                  'Allow participation in different programs with this plan.',
                                content: (
                                  <StorybookComponents.Placeholder>
                                    Online Programs content
                                  </StorybookComponents.Placeholder>
                                ),
                              },
                              {
                                title: 'Groups',
                                subtitle:
                                  'Give clients access to exclusive groups.',
                                content: (
                                  <StorybookComponents.Placeholder>
                                    Groups content
                                  </StorybookComponents.Placeholder>
                                ),
                              },
                            ]}
                          />
                        </Box>
                      </Card>
                    </Cell>
                  </Layout>
                </Box>
              </Page.Content>
            </Page>
          }
        />
      </Modal>
    </Card>
  );
};
```

#### Modal with marketing layout

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.

```jsx
() => {
  const [shown, setShown] = React.useState(false);

  return (
    <Card>
      <Card.Header
        title="Add Logo to your website"
        subtitle="Customize your website to match the colors and style of your logo."
        suffix={
          <Button
            size="small"
            priority="secondary"
            onClick={() => setShown(true)}
          >
            Connect Website
          </Button>
        }
      />
      <Modal
        isOpen={shown}
        onRequestClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        screen="desktop"
      >
        <CustomModalLayout
          width="720px"
          removeContentPadding
          onCloseButtonClick={() => setShown(false)}
          content={
            <Card>
              <MarketingLayout
                size="medium"
                title="Wix unlimited website Premium plan"
                description="Get a customizable website, designed to match the colors and style of your logo."
                actions={
                  <Button onClick={() => setShown(false)}>Add to Cart</Button>
                }
                image={
                  <Box height="156px">
                    <Image src="MarketingIllustration1.png" transparent />
                  </Box>
                }
              />
            </Card>
          }
        />
      </Modal>
    </Card>
  );
};
```

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

```jsx
() => {
  const [shown, setShown] = React.useState(false);

  return (
    <Card>
      <Card.Header
        title="Plan policies"
        subtitle="Add your own terms and conditions for this plan."
        suffix={
          <TextButton
            size="small"
            prefixIcon={<Icons.AddSmall />}
            onClick={() => setShown(true)}
          >
            Add Policy
          </TextButton>
        }
      />
      <Modal
        isOpen={shown}
        onRequestClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        screen="desktop"
      >
        <CustomModalLayout
          primaryButtonText="Add Policy"
          secondaryButtonText="Cancel"
          onCloseButtonClick={() => setShown(false)}
          secondaryButtonOnClick={() => setShown(false)}
          primaryButtonOnClick={() => setShown(false)}
          overflowY="none"
          width="600px"
          title="Add new pricing plan policy"
          content={
            <Layout>
              <Cell>
                <FormField label="Policy title">
                  <Input placeholder="Enter title here" />
                </FormField>
              </Cell>
              <Cell>
                <FormField label="Terms & Conditions">
                  <InputArea
                    placeholder="e.g., Free trial, renewal, cancellation, and refunds."
                    rows={6}
                    maxLength={1000}
                    hasCounter
                    resizable
                  />
                </FormField>
              </Cell>
            </Layout>
          }
        />
      </Modal>
    </Card>
  );
};
```

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

```jsx
() => {
  const [shown, setShown] = React.useState(false);

  return (
    <>
      <Button
        size="small"
        priority="secondary"
        prefixIcon={<Icons.PreviewSmall />}
        onClick={() => setShown(true)}
      >
        Click to see a modal
      </Button>
      <Modal
        isOpen={shown}
        onRequestClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        screen="desktop"
      >
        <CustomModalLayout
          primaryButtonText="Save"
          secondaryButtonText="Cancel"
          onCloseButtonClick={() => setShown(false)}
          onHelpButtonClick={() => {}}
          secondaryButtonOnClick={() => setShown(false)}
          primaryButtonOnClick={() => setShown(false)}
          removeContentPadding
          title="Modal title as H2"
          content={
            <Page>
              <Page.Content>
                <Box marginTop={5} display="block">
                  <Layout>
                    <Cell span={12}>
                      <Card>
                        <Card.Header title="Card title as H3" />
                        <Card.Divider />
                        <Card.Content>
                          <StorybookComponents.Placeholder>
                            <Box
                              verticalAlign="middle"
                              align="center"
                              height="180px"
                            >
                              <Text>Card content</Text>
                            </Box>
                          </StorybookComponents.Placeholder>
                        </Card.Content>
                      </Card>
                    </Cell>
                  </Layout>
                </Box>
              </Page.Content>
            </Page>
          }
        />
      </Modal>
    </>
  );
};
```

## Code

```jsx
import { CustomModalLayout } from '@wix/design-system';
```

### Props

| 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., <Loader/>) for the primary button. |
| `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. |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { CustomModalLayoutUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { CustomModalLayoutTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { CustomModalLayoutTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { CustomModalLayoutTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

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

## 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](invalid-url)) — 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](invalid-url))
- **1.202.0** (2025-06-27) — breaking: tokenization ([#15000](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **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