> 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: Modals and overlays

## Article: Modals and Overlays

## Article Link: https://dev.wix.com/docs/wix-design-system/guidelines/interaction-behavior/modals-and-overlays.md

## Article Content:

<!-- heading -->


# Modals and Overlays


<!-- end heading -->


Modals and overlays are essential UI patterns that temporarily take control of the user's attention to communicate important information or collect input. When used well, they streamline workflows. When overused they frustrate users and break flows.


This article provides clear, actionable guidelines for choosing and implementing the right modal component for any given use case - both across  desktop and mobile devices.


## 1. Key principles




**1. Minimize disruption.**<br>
Use the least intrusive overlay that still accomplishes the goal. Not every task needs a full-screen takeover.


**2. Preserve context when needed.**<br>
If the user's action relates to content on the page behind, use an overlay that keeps that content visible


**3. Always provide a clear exit.**<br>
Every modal must have an obvious way to dismiss it - close, cancel buttons, or tap/swipe-outside.


**4. Match the component to the content.**<br>
Content length, complexity, and user expectations should determine which modal type you select.


**5. Respect platform conventions.**<br>
Desktop and mobile have interaction expectations. A pattern that works well on desktop may need a different component on mobile.


### 1.1 User-triggered vs. system-triggered
* **User-triggered overlay** is triggered by the user themselves. For example, when the user clicks 'Delete Item', they can trigger the modal 'Are you sure?'. In other words, the modal or overlay doesn't open until the user triggers it by performing an action.
* **System-triggered** - is triggered without the action of the user. Think of promotions or onboarding, when the system pushes an overlay upon entering the site. The user doesn't perform any action that triggers the overlay, but the system still shows it.


## 2. Component overview


An overview of what's available. For detailed rules and usage patterns, see each component's story page.




### 2.1 Desktop modals


Desktop modals in WDS follow a centered overlay pattern with a backdrop. The three primary components serve distinct purposes and shouldn't be used interchangeably.


**1. [Announcement Modal](#/component/announcementmodallayout)**<br>
Feature promotions, upsells, and optional entry points. Non-blocking, can include illustration, headline, and CTA. The user can dismiss and continue.
![Announcement Modal Shape](https://wixmp-833713b177cebf373f611808.wixmp.com/images/9daae88d389c7240001b96f650af1274.png)


**2. [Message Modal](#/component/messagemodallayout)**<br>
Short, focused confirmations and alerts. Small, compact, always user-initiated. Used for destructive actions and simple binary decisions.
![Message Modal Shape](https://wixmp-833713b177cebf373f611808.wixmp.com/images/1bc1be8433ebb5a4a98858b284e01a58.png)


**3. [Custom Modal](#/component/custommodallayout)**<br>
Flexible container for forms, multi-step flows, and rich content. User-initiated only.
![Custom Modal Shape](https://wixmp-833713b177cebf373f611808.wixmp.com/images/762bda06d82d05a0e07e2dd0a38ceb3b.png)


![Desktop modal map](https://wixmp-833713b177cebf373f611808.wixmp.com/images/fd0df8448692fee8426597324ca61c28.png)




### 2.2 Mobile modals


Mobile modals and overlays offer a variation of layouts for different scenarios. They are more flexible compared to desktop options and can be used interchangeably depending on the use case.


**1. [Full Screen Modal](#/component/fullscreenmodallayout)**<br>
Full-screen takeover for heavy interruptions: promotions, multi-step flows, long forms. Highly customizable. Can be system-triggered.
![FullScreen Modal Shape](https://wixmp-833713b177cebf373f611808.wixmp.com/images/a3e8a5ce1ebe86a138ad9bc54faaa011.png)


**2. [Drawer](#/component/drawer)**<br>
Slides up from the bottom. Adapts height to content. Ideal for contextual actions, short forms, action sheets, and anything where page context matters. Replaces desktop popovers and dropdowns.
![Drawer Shape](https://wixmp-833713b177cebf373f611808.wixmp.com/images/e9745796b3a715d518d003d0ffdebcfc.png)


**3. [Mobile Modal](#/component/modalmobilelayout)**<br>
Centered overlay for summaries, end-of-journey confirmations, and short content where the user doesn't need the page behind.
![Mobile Modal Shape](https://wixmp-833713b177cebf373f611808.wixmp.com/images/d0fca1363ec67afa01cf34792f91df32.png)


![Mobile modal map](https://wixmp-833713b177cebf373f611808.wixmp.com/images/5c8e9fd9a972cecd6727d982deeb9b6e.png)




## 3. Desktop-mobile mapping


As Wix is increasing the number of mobile products, it's become critical for desktop and mobile components to work responsively between each other. The same user need often requires a fundamentally different component on each platform.


**Promotions** <br/>
[Announcement Modal](#/component/announcementmodallayout) (desktop) -> [Full Screen Modal](#/component/fullscreenmodallayout) (mobile). For smaller promotions, [Drawer](#/component/drawer) works on mobile.


![Announcement modals turn into full screen modals on mobile](https://wixmp-833713b177cebf373f611808.wixmp.com/images/5322c8cf3b0c6dd0e364a776102d65c5.png)


**Confirmation** <br/>
[Message Modal](#/component/messagemodallayout) (desktop) -> [Drawer](#/component/drawer) (mobile, if context matters) or [Mobile Modal](#/component/modalmobilelayout) (if context doesn't matter)


![MessageModals turn into Mobile Modal or Drawer on mobile](https://wixmp-833713b177cebf373f611808.wixmp.com/images/594db233323af3cee7139cf21c4f3154.png)


![Use Drawer on mobile where context matters](https://wixmp-833713b177cebf373f611808.wixmp.com/images/7cbc2243564f69d57d5661df81932eb9.png)


**Forms** <br/>
[Custom Modal](#/component/custommodallayout) (desktop) -> [Drawer](#/component/drawer) extended (mobile, shorter forms) or [Full Screen Modal](#/component/fullscreenmodallayout) (mobile, complex forms).


![For simple flows you can use drawers on mobile](https://wixmp-833713b177cebf373f611808.wixmp.com/images/28277293fd704b211abd3e2fa4c4a23f.png)


![For complex flows use full screen modal on mobile](https://wixmp-833713b177cebf373f611808.wixmp.com/images/687e50d02f2694fe4d0cc924e1e0af32.png)


**Action menus** <br/>
[PopoverMenu](#/component/popovermenu) / [Dropdown](#/component/dropdown) (desktop) -> [Drawer](#/component/drawer) (mobile)


![Popovers and dropdowns become drawers on mobile](https://wixmp-833713b177cebf373f611808.wixmp.com/images/bad469627000abf42d032577bb6c62b4.png)


Use this table as a quick reference guide when deciding which type of overlay or modal to use:


![Cross-platform map](https://wixmp-833713b177cebf373f611808.wixmp.com/images/17f3999f17ee785267b5a8156aeba66c.png)


## 4. Best practices and anti-patterns


### 4.1 Content guidelines


For more extensive and detailed guidelines reference [UX Writing page](https://coda.io/d/UX-writing_dbwUPcli6Z7/Content-guidelines_suEsL6je#_luNg568e)


<br>


<!-- dodont -->
<!-- dodont image -->
![Titles should clearly state the purpose - never use generic titles like "Confirm" or "Alert"](https://wixmp-833713b177cebf373f611808.wixmp.com/images/77ffd3c08d7568326a2b59745ba7e54f.png)
<!-- end dodont image -->
<!-- dodont content -->
#### Do 
Titles should clearly state the purpose - never use generic titles like "Confirm" or "Alert"
<!-- end dodont content -->
<!-- end dodont --> 


<br>


<!-- dodont -->
<!-- dodont image -->
![Body text should be concise and action-oriented. More than 3-4 sentences suggests a modal may not be the right pattern](https://wixmp-833713b177cebf373f611808.wixmp.com/images/c35742a0c2a3d4e6eebc21fa171d8533.png)
<!-- end dodont image -->
<!-- dodont content -->
#### Do 
Body text should be concise. More than 3-4 sentences suggests a modal may not be the right pattern.
<!-- end dodont content -->
<!-- end dodont --> 


<br>


<!-- dodont -->
<!-- dodont image -->
![Primary action buttons should use specific verbs ("Delete program", "Start import") rather than vague labels ("OK", "Yes")](https://wixmp-833713b177cebf373f611808.wixmp.com/images/b9c08af879183602b75190fe39fed2a6.png)
<!-- end dodont image -->
<!-- dodont content -->
#### Do 
Primary action buttons should use specific verbs ("Delete program", "Start import") rather than vague labels ("OK", "Yes")
<!-- end dodont content -->
<!-- end dodont --> 


<br>


<!-- dodont -->
<!-- dodont image -->
![For destructive actions, make consequences clear in body text and use a visually distinct primary button](https://wixmp-833713b177cebf373f611808.wixmp.com/images/f7721da1e0d35cb013b106572467628f.png)
<!-- end dodont image -->
<!-- dodont content -->
#### Do 
For destructive actions, make consequences clear in body text and use a visually distinct primary button.
<!-- end dodont content -->
<!-- end dodont --> 




### 4.2 Accessibility guidelines


Getting accessibility correctly with modals and overlays is critical. Getting this wrong means some users can't use or escape the overlay. Wix Design System team made so that modals and overlays are accessible out-of-the box, but every team is responsible for any overrides to be accessible as well.


**1. All modals must trap focus while open.** <br/>
Focus must be trapped inside the modal while it's open. Tabbing past the last focusable element should cycle back to the first. After dismissal, return focus to the triggering element.


Never auto-focus a destructive action button. In a "Delete this item?" modal, focus should land on "Cancel", not "Delete".


![Tab focus in the modal](https://wixmp-833713b177cebf373f611808.wixmp.com/images/cf2aa095a4a98090b2a0cf11bd4edff6.gif)


**2. Escape key should dismiss on desktop.** <br/>


These are the expected behaviour patterns on overlays and modals:
- Escape -> dismisses the modal
- Tab -> moves focus to the next focusable element in the modal
- Shift+Tab -> moves focus to the previous focusable element
- Enter -> activates the focused element


![Escape key dismiss the modal](https://wixmp-833713b177cebf373f611808.wixmp.com/images/f693c96692a4c49b750d904dd638e226.gif)


**3. Screen readers must announce the modal title on open.** <br/>
**4. Ensure sufficient color contrast for all modal text.** <br/>
**5. Mobile touch target must be at least 24x24 pixels**


### 4.3 Anti-patterns


<!-- dodont -->
<!-- dodont image -->
![Modal stacking](https://wixmp-833713b177cebf373f611808.wixmp.com/images/1de6e062824cc8341d4f704511d77f15.gif)
<!-- end dodont image -->
<!-- dodont content -->
#### Don't 
Avoid opening a modal on top of another modal. Consider alternative solutions like content replacement or in-line alerts for non-blocking feedback. If the stacking is unavoidable, ensure you don't stack a lot of layers, and the top layer doesn't introduce complex new decisions.
<!-- end dodont content -->
<!-- end dodont --> 


<br>


<!-- dodont -->
<!-- dodont image -->
![System triggered modals should be rare](https://wixmp-833713b177cebf373f611808.wixmp.com/images/a456ee31ff1ec4d888a7c28f3547f6e0.png)
<!-- end dodont image -->
<!-- dodont content -->
#### Don't 
Never use system-triggered modals. It should be limited to promotions or critical alerts. Unexpected modals frustrate users.
<!-- end dodont content -->
<!-- end dodont --> 


<br>


<!-- dodont -->
<!-- dodont image -->
![Wrong component for content](https://wixmp-833713b177cebf373f611808.wixmp.com/images/34c22ec3ea79e9d5249bd6386fa2b066.png)
<!-- end dodont image -->
<!-- dodont content -->
#### Don't
Use the wrong component for content. Don't use MessageModal for long content, don't use FullScreenModalLayout for a simple yes/no. Check with the decision tree or with the Wix Design System team member.
<!-- end dodont content -->
<!-- end dodont --> 


<br>


<!-- dodont -->
<!-- dodont image -->
![Missing dismiss path](https://wixmp-833713b177cebf373f611808.wixmp.com/images/0eeca5973a84117e98626b405c3acde7.png)
<!-- end dodont image -->
<!-- dodont content -->
#### Don't 
Miss the dismiss path. Every modal must have at least one way to close without completing the action.
<!-- end dodont content -->
<!-- end dodont --> 


---


## Related components


* [Announcement Modal](#/component/announcementmodallayout)
* [Message Modal](#/component/messagemodallayout)
* [Custom Modal](#/component/custommodallayout)
* [Drawer](#/component/drawer)
* [Full Screen Modal](#/component/fullscreenmodallayout)