[Modal] Document the 'Focus trap' limitation (#18643)

mui · Dec 2, 2019 · 0cdffb9 · 0cdffb9
1 parent 386bbf9
commit 0cdffb9
Show file tree

Hide file tree

Showing 2 changed files with 17 additions and 0 deletions.
diff --git a/docs/src/pages/components/dialogs/dialogs.md b/docs/src/pages/components/dialogs/dialogs.md
@@ -121,6 +121,10 @@ Try the demo below to see what we mean:
 
 {{"demo": "pages/components/dialogs/ScrollDialog.js"}}
 
+## Limitations
+
+Follow the [Modal limitations section](/components/modal/#limitations).
+
 ## Accessibility
 
 Follow the [Modal accessibility section](/components/modal/#accessibility).
diff --git a/docs/src/pages/components/modal/modal.md b/docs/src/pages/components/modal/modal.md
@@ -62,6 +62,19 @@ In order to display the modal, you need to disable the portal feature with the `
 
 {{"demo": "pages/components/modal/ServerModal.js"}}
 
+## Limitations
+
+### Focus trap
+
+The modal moves the focus back to the body of the component if the focus tries to escape it.
+
+This is done for accessibility purposes, however, it might create issues.
+In the event the users need to interact with another part of the page, e.g. with a chatbot window, you can disable the behavior:
+
+```jsx
+<Modal disableEnforceFocus />
+```
+
 ## Accessibility
 
 (WAI-ARIA: https://www.w3.org/TR/wai-aria-practices/#dialog_modal)