> 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: Modal Component

## Article: Modal Component

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

## Article Content:

# Modal

_Components/Overlays/Modal_

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

## Overview

```jsx
() => {
  const [isModalOpened, setModalOpened] = React.useState(false);
  const [checked, setChecked] = React.useState(false);

  const openModal = () => setModalOpened(true);
  const closeModal = () => setModalOpened(false);

  const renderModalContent = () => (
    <MessageModalLayout
      onCloseButtonClick={() => setModalOpened(false)}
      secondaryButtonOnClick={() => setModalOpened(false)}
      primaryButtonOnClick={() => setModalOpened(false)}
      primaryButtonText="Leave Page"
      secondaryButtonText="Cancel"
      title="Leave page?"
      content={
        <Text>When you leave this page, you'll lose unsaved changes.</Text>
      }
    />
  );

  return (
    <Box align="center">
      <Button onClick={openModal} prefixIcon={<Icons.OpenModal />}>
        Open Modal
      </Button>
      <Modal isOpen={isModalOpened} onRequestClose={closeModal}>
        {renderModalContent()}
      </Modal>
    </Box>
  );
};
```

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

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

  const openModal = () => setModalOpened(true);
  const closeModal = () => setModalOpened(false);

  const renderModalContent = () => (
    <StorybookComponents.Placeholder skin="light" width="600px" height="600px">
      <StorybookComponents.Stack
        flexDirection="column"
        alignItems="center"
        padding="30px"
      >
        <Text light>Modal content goes here.</Text>
        <TextButton onClick={closeModal} underline="always" skin="light">
          Close Modal
        </TextButton>
      </StorybookComponents.Stack>
    </StorybookComponents.Placeholder>
  );

  return (
    <StorybookComponents.Stack>
      <Button onClick={openModal} prefixIcon={<Icons.OpenModal />}>
        Open Modal
      </Button>
      <Modal isOpen={isModalOpened} onRequestClose={closeModal}>
        {renderModalContent()}
      </Modal>
    </StorybookComponents.Stack>
  );
};
```

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

```jsx
() => {
  const [isModalOpened, setModalOpened] = React.useState(false);
  const [currentScreen, setCurrentScreen] = React.useState(null);

  const openModal = (screen) => {
    setCurrentScreen(screen);
    setModalOpened(true);
  };
  const closeModal = () => setModalOpened(false);

  const renderModalContent = () => (
    <StorybookComponents.Placeholder skin="light">
      <StorybookComponents.Stack padding="30px">
        <TextButton onClick={closeModal} underline="always" skin="light">
          Close Modal
        </TextButton>
      </StorybookComponents.Stack>
    </StorybookComponents.Placeholder>
  );

  return (
    <StorybookComponents.Stack>
      <Button
        prefixIcon={<Icons.FullScreen />}
        onClick={() => openModal('full')}
      >
        Full
      </Button>

      <Button
        prefixIcon={<Icons.Desktop />}
        onClick={() => openModal('desktop')}
      >
        Desktop
      </Button>

      <Button prefixIcon={<Icons.Mobile />} onClick={() => openModal('mobile')}>
        Mobile
      </Button>
      <Modal
        screen={currentScreen}
        isOpen={isModalOpened}
        onRequestClose={closeModal}
      >
        {renderModalContent()}
      </Modal>
    </StorybookComponents.Stack>
  );
};
```

#### Navigation controls

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

```jsx
() => {
  const content = [
    {
      title: 'Title (Item 1)',
      body: 'Body content (Item 1).',
    },
    {
      title: 'Title (Item 2)',
      body: 'Body content (Item 2).',
    },
    {
      title: 'Title (Item 3)',
      body: 'Body content (Item 3).',
    },
  ];
  const [isModalOpened, setModalOpened] = React.useState(false);
  const [currentContent, setCurrentContent] = React.useState(0);

  const openModal = () => setModalOpened(true);
  const closeModal = () => setModalOpened(false);

  const renderModalContent = () => {
    const { title, body } = content[currentContent];
    return (
      <MessageModalLayout
        onCloseButtonClick={() => closeModal()}
        primaryButtonOnClick={() => closeModal()}
        secondaryButtonOnClick={() => closeModal()}
        primaryButtonText={'Save'}
        secondaryButtonText={'Cancel'}
        title={title}
      >
        <Text>{body}</Text>
      </MessageModalLayout>
    );
  };

  return (
    <StorybookComponents.Stack>
      <Button onClick={openModal} prefixIcon={<Icons.OpenModal />}>
        Open Modal
      </Button>
      <Modal
        isOpen={isModalOpened}
        onRequestClose={closeModal}
        showNavigationPreviousButton
        showNavigationNextButton
        navigationPreviousLabel="Previous"
        navigationNextLabel="Next"
        onNavigationClickPrevious={() =>
          setCurrentContent(
            (currentContent > 0 ? currentContent : content.length) - 1,
          )
        }
        onNavigationClickNext={() =>
          setCurrentContent((currentContent + 1) % content.length)
        }
      >
        {renderModalContent()}
      </Modal>
    </StorybookComponents.Stack>
  );
};
```

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

```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>
  );
};
```

## Code

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

### Props

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

## Testkit

Import the driver matching your test environment:

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

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

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

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

### Driver methods

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

## 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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **1.232.0** (2025-11-28) — fix: make shadow-surface-modal responsive ([#15543](invalid-url))
- **1.228.0** (2025-11-18) — maintenance release, no component-specific changes
- **1.225.0** (2025-11-07) — feat: add transition animations ([#15466](invalid-url))
- **1.212.0** (2025-08-11) — feat: blur backdrop ([#15172](invalid-url))
- **1.203.0** (2025-07-01) — breaking: tokenization ([#15010](invalid-url))
- **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](invalid-url))
- **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