diff --git a/src/components/overlay/README.md b/src/components/overlay/README.md
index c2c22a1351e..e2fc6ca0e9b 100644
--- a/src/components/overlay/README.md
+++ b/src/components/overlay/README.md
@@ -769,3 +769,10 @@ This example also demonstrates additional accessibility markup.
 
 <!-- b-overlay-example-form.vue -->
 ```
+
+### Using in `<b-modal>`
+
+The modal body has `position: relative;` set, so when using `<b-overlay no-wrap ...>` in the modal
+body only the modal body will be obscured. If you wish to obscure the entire modal (including the
+header and footer), you will need to set the `<b-modal>` prop `body-class` to `position-static`, and
+also set  the `rounded` prop on `<b-overlay>`.