@react-ui-org/react-ui 0.50.2 → 0.52.0

package/src/lib/components/Modal/README.mdx

@@ -14,6 +14,7 @@ import {
 } from 'docz'
 import {
   Button,
+  CheckboxField,
   FormLayout,
   Modal,
   ModalBody,
@@ -22,7 +23,9 @@ import {
   ModalFooter,
   ModalHeader,
   ModalTitle,
+  Radio,
   ScrollView,
+  TextArea,
   TextField,
   Toolbar,
   ToolbarGroup,
@@ -55,11 +58,7 @@ And use it:
     const modalCloseButtonRef = React.useRef();
     return (
       <>
-        <Button
-          label="Launch modal"
-          onClick={() => setModalOpen(true)}
-          priority="outline"
-        />
+        <Button label="Launch modal" onClick={() => setModalOpen(true)} />
         <div>
           {modalOpen && (
             <Modal
@@ -86,6 +85,7 @@ And use it:
                   ref={modalPrimaryButtonRef}
                 />
                 <Button
+                  color="secondary"
                   label="Close"
                   onClick={() => setModalOpen(false)}
                   priority="outline"
@@ -117,12 +117,15 @@ See [API](#api) for all available options.
 
 - Modal **automatically focuses the first non-disabled form field** by default
   which allows users to confirm the modal by hitting the enter key. When no
-  field is found then the primary button (in the footer) is focused. To turn
-  this feature off, set the `autofocus` prop to `false`.
+  field is found then the primary button (in the footer) is focused. If there
+  are neither, it tries to focus any other focusable elements. In case there
+  are none, or [autoFocus](#autoFocus) is disabled, Modal itself is focused.
 
 - **Avoid stacking** of modals. While it may technically work, the modal is just
   not designed for that.
 
+📖 [Read more about modals at Nielsen Norman Group.][nng-modal]
+
 ## Composition
 
 Modal is decomposed into the following components:
@@ -152,7 +155,6 @@ e.g. dialog modal, blocking modal, scrollable modal, etc.
             setModalOpen(1);
             setTimeout(() => setModalOpen(null), 2500);
           }}
-          priority="outline"
         />
         <Button
           label="Launch blocking modal with title"
@@ -160,17 +162,14 @@ e.g. dialog modal, blocking modal, scrollable modal, etc.
             setModalOpen(2);
             setTimeout(() => setModalOpen(null), 3500);
           }}
-          priority="outline"
         />
         <Button
           label="Launch modal as dialog"
           onClick={() => setModalOpen(3)}
-          priority="outline"
         />
         <Button
           label="Launch modal as form"
           onClick={() => setModalOpen(4)}
-          priority="outline"
         />
         <div>
           {modalOpen === 1 && (
@@ -227,6 +226,7 @@ e.g. dialog modal, blocking modal, scrollable modal, etc.
                   ref={modalPrimaryButtonRef}
                 />
                 <Button
+                  color="secondary"
                   label="Close"
                   onClick={() => setModalOpen(false)}
                   priority="outline"
@@ -259,6 +259,7 @@ e.g. dialog modal, blocking modal, scrollable modal, etc.
                   ref={modalPrimaryButtonRef}
                 />
                 <Button
+                  color="secondary"
                   label="Close"
                   onClick={() => setModalOpen(false)}
                   priority="outline"
@@ -305,7 +306,6 @@ There are two ways how to position elements within the ModalHeader:
             setModalOpen(true);
             setVariant(1);
           }}
-          priority="outline"
         />
         <Button
           label="Launch without close button"
@@ -313,7 +313,6 @@ There are two ways how to position elements within the ModalHeader:
             setModalOpen(true);
             setVariant(2);
           }}
-          priority="outline"
         />
         <Button
           label="Launch without close button and with centered title"
@@ -321,7 +320,6 @@ There are two ways how to position elements within the ModalHeader:
             setModalOpen(true);
             setVariant(3);
           }}
-          priority="outline"
         />
         <Button
           label="Launch with custom layout"
@@ -329,7 +327,6 @@ There are two ways how to position elements within the ModalHeader:
             setModalOpen(true);
             setVariant(4);
           }}
-          priority="outline"
         />
         <div>
           {modalOpen && (
@@ -384,6 +381,7 @@ There are two ways how to position elements within the ModalHeader:
                   ref={modalPrimaryButtonRef}
                 />
                 <Button
+                  color="secondary"
                   label="Close"
                   onClick={() => setModalOpen(false)}
                   priority="outline"
@@ -432,44 +430,8 @@ There are two ways to position buttons within the ModalFooter:
     return (
       <>
         <Button
-          label="Launch with footer justified to start"
-          onClick={() => {
-            setModalOpen(true);
-            setModalJustify('start');
-          }}
-          priority="outline"
-        />
-        <Button
-          label="Launch with footer justified to center"
-          onClick={() => {
-            setModalOpen(true);
-            setModalJustify('center');
-          }}
-          priority="outline"
-        />
-        <Button
-          label="Launch with footer justified to end"
-          onClick={() => {
-            setModalOpen(true);
-            setModalJustify('end');
-          }}
-          priority="outline"
-        />
-        <Button
-          label="Launch with footer justified with space between"
-          onClick={() => {
-            setModalOpen(true);
-            setModalJustify('space-between');
-          }}
-          priority="outline"
-        />
-        <Button
-          label="Launch with footer with custom layout"
-          onClick={() => {
-            setModalOpen(true);
-            setModalJustify('stretch');
-          }}
-          priority="outline"
+          label="Launch modal with footer variants"
+          onClick={() => setModalOpen(true)}
         />
         <div>
           {modalOpen && (
@@ -478,15 +440,38 @@ There are two ways to position buttons within the ModalFooter:
               primaryButtonRef={modalPrimaryButtonRef}
             >
               <ModalHeader>
-                <ModalTitle>Delete the user?</ModalTitle>
+                <ModalTitle>Footer justification</ModalTitle>
                 <ModalCloseButton onClick={() => setModalOpen(false)} />
               </ModalHeader>
               <ModalBody>
                 <ModalContent>
-                  <p>
-                    Do you really want to delete the user <code>admin</code>?
-                    This cannot be undone.
-                  </p>
+                  <Radio
+                    label="Footer justification"
+                    onChange={(e) => setModalJustify(e.target.value)}
+                    options={[
+                      {
+                        label: 'start',
+                        value: 'start',
+                      },
+                      {
+                        label: 'center',
+                        value: 'center',
+                      },
+                      {
+                        label: 'end',
+                        value: 'end',
+                      },
+                      {
+                        label: 'space-between',
+                        value: 'space-between',
+                      },
+                      {
+                        label: 'stretch (with a custom layout)',
+                        value: 'stretch',
+                      },
+                    ]}
+                    value={modalJustify}
+                  />
                 </ModalContent>
               </ModalBody>
               <ModalFooter justify={modalJustify}>
@@ -514,6 +499,7 @@ There are two ways to position buttons within the ModalFooter:
                           </ToolbarGroup>
                         <ToolbarItem>
                           <Button
+                            color="secondary"
                             label="Close"
                             onClick={() => setModalOpen(false)}
                             priority="outline"
@@ -524,12 +510,12 @@ There are two ways to position buttons within the ModalFooter:
                     ) : (
                       <>
                         <Button
-                          color="danger"
-                          label="Delete"
+                          label="OK"
                           onClick={() => setModalOpen(false)}
                           ref={modalPrimaryButtonRef}
                         />
                         <Button
+                          color="secondary"
                           label="Close"
                           onClick={() => setModalOpen(false)}
                           priority="outline"
@@ -566,7 +552,6 @@ Modals of any size automatically shrink when they cannot fit the screen width.
             setModalSize('small');
             setModalOpen(true);
           }}
-          priority="outline"
         />
         <Button
           label="Launch medium modal"
@@ -574,7 +559,6 @@ Modals of any size automatically shrink when they cannot fit the screen width.
             setModalSize('medium');
             setModalOpen(true);
           }}
-          priority="outline"
         />
         <Button
           label="Launch large modal"
@@ -582,7 +566,6 @@ Modals of any size automatically shrink when they cannot fit the screen width.
             setModalSize('large');
             setModalOpen(true);
           }}
-          priority="outline"
         />
         <Button
           label="Launch fullscreen modal"
@@ -590,7 +573,6 @@ Modals of any size automatically shrink when they cannot fit the screen width.
             setModalSize('fullscreen');
             setModalOpen(true);
           }}
-          priority="outline"
         />
         <div>
           {modalOpen && (
@@ -619,6 +601,7 @@ Modals of any size automatically shrink when they cannot fit the screen width.
                   ref={modalPrimaryButtonRef}
                 />
                 <Button
+                  color="secondary"
                   label="Close"
                   onClick={() => setModalOpen(false)}
                   priority="outline"
@@ -645,7 +628,6 @@ On top of that, the modal can adjust to the width of its content.
         <Button
           label="Launch auto-width modal"
           onClick={() => setModalOpen(true)}
-          priority="outline"
         />
         <div>
           {modalOpen && (
@@ -674,6 +656,7 @@ On top of that, the modal can adjust to the width of its content.
                   ref={modalPrimaryButtonRef}
                 />
                 <Button
+                  color="secondary"
                   label="Close"
                   onClick={() => setModalOpen(false)}
                   priority="outline"
@@ -688,57 +671,61 @@ On top of that, the modal can adjust to the width of its content.
   }}
 </Playground>
 
-👉 Please note the auto width may not function correctly in combination with
-other auto-layout mechanisms, e.g. the auto-width
-[FormLayout](/components/form-layout#label-width). It's just too much
-magic that doesn't work together (yet?) 🎩.
+## Position
 
-👉 Beware of horizontal FormLayout inside `small` modals. While automatic
-overflow handling comes to the rescue in this kind of scenario, you will be
-better off with the combination of auto-sized modal and horizontal FormLayout
-with a fixed label width (i.e. any other than `auto`, see the previous note).
+Modal can be aligned either to the top or center of the screen.
 
 <Playground>
   {() => {
     const [modalOpen, setModalOpen] = React.useState(false);
+    const [modalPosition, setModalPosition] = React.useState('center');
     const modalPrimaryButtonRef = React.useRef();
     const modalCloseButtonRef = React.useRef();
     return (
       <>
         <Button
-          label="Launch auto-with modal with a form"
-          onClick={() => setModalOpen(true)}
-          priority="outline"
+          label="Launch modal at center"
+          onClick={() => {
+            setModalPosition('center');
+            setModalOpen(true);
+          }}
+        />
+        <Button
+          label="Launch modal at top"
+          onClick={() => {
+            setModalPosition('top');
+            setModalOpen(true);
+          }}
         />
         <div>
           {modalOpen && (
             <Modal
               closeButtonRef={modalCloseButtonRef}
+              position={modalPosition}
               primaryButtonRef={modalPrimaryButtonRef}
-              size="auto"
             >
               <ModalHeader>
-                <ModalTitle>Form inside modal</ModalTitle>
+                <ModalTitle>Delete the user?</ModalTitle>
                 <ModalCloseButton onClick={() => setModalOpen(false)} />
               </ModalHeader>
               <ModalBody>
                 <ModalContent>
-                  <FormLayout fieldLayout="horizontal">
-                    <TextField label="A form element" />
-                    <TextField label="Another form element" />
-                    <TextField label="Yet another one" />
-                  </FormLayout>
+                  <p>
+                    Do you really want to delete the user <code>admin</code>?
+                    This cannot be undone.
+                  </p>
                 </ModalContent>
               </ModalBody>
               <ModalFooter>
                 <Button
-                  color="primary"
-                  label="Save"
+                  color="danger"
+                  label="Delete"
                   onClick={() => setModalOpen(false)}
                   ref={modalPrimaryButtonRef}
                 />
                 <Button
-                  label="Cancel"
+                  color="secondary"
+                  label="Close"
                   onClick={() => setModalOpen(false)}
                   priority="outline"
                   ref={modalCloseButtonRef}
@@ -752,62 +739,64 @@ with a fixed label width (i.e. any other than `auto`, see the previous note).
   }}
 </Playground>
 
-## Position
+## Forms in Modals
 
-Modal can be aligned either to the top or center of the screen.
+You can safely place a FormLayout into a Modal of any size, including the
+auto-width Modal.
 
 <Playground>
   {() => {
     const [modalOpen, setModalOpen] = React.useState(false);
-    const [modalPosition, setModalPosition] = React.useState('center');
+    const [agree, setAgree] = React.useState(true);
     const modalPrimaryButtonRef = React.useRef();
     const modalCloseButtonRef = React.useRef();
     return (
       <>
         <Button
-          label="Launch modal at center"
-          onClick={() => {
-            setModalPosition('center');
-            setModalOpen(true);
-          }}
-          priority="outline"
-        />
-        <Button
-          label="Launch modal at top"
-          onClick={() => {
-            setModalPosition('top');
-            setModalOpen(true);
-          }}
-          priority="outline"
+          label="Launch auto-width modal with auto-width form"
+          onClick={() => setModalOpen(true)}
         />
         <div>
           {modalOpen && (
             <Modal
               closeButtonRef={modalCloseButtonRef}
-              position={modalPosition}
               primaryButtonRef={modalPrimaryButtonRef}
+              size="auto"
             >
               <ModalHeader>
-                <ModalTitle>Delete the user?</ModalTitle>
+                <ModalTitle>Auto-width form inside auto-width modal</ModalTitle>
                 <ModalCloseButton onClick={() => setModalOpen(false)} />
               </ModalHeader>
               <ModalBody>
                 <ModalContent>
-                  <p>
-                    Do you really want to delete the user <code>admin</code>?
-                    This cannot be undone.
-                  </p>
+                  <FormLayout autoWidth fieldLayout="horizontal">
+                    <TextField
+                      label="A form element"
+                      validationState="warning"
+                      validationText={`Account with this name already exists,
+                       pick a different one.`
+                      }
+                    />
+                    <TextField label="Another form element" />
+                    <TextField label="Yet another one" />
+                    <CheckboxField
+                      checked={agree}
+                      label="I agree"
+                      onChange={() => setAgree(!agree)}
+                    />
+                  </FormLayout>
                 </ModalContent>
               </ModalBody>
               <ModalFooter>
                 <Button
-                  color="danger"
-                  label="Delete"
+                  color="primary"
+                  label="Save"
                   onClick={() => setModalOpen(false)}
                   ref={modalPrimaryButtonRef}
                 />
                 <Button
-                  label="Close"
+                  color="secondary"
+                  label="Cancel"
                   onClick={() => setModalOpen(false)}
                   priority="outline"
                   ref={modalCloseButtonRef}
@@ -821,6 +810,14 @@ Modal can be aligned either to the top or center of the screen.
   }}
 </Playground>
 
+👉 Inside Modal, we recommend using the `autoWidth` option of FormLayout. This
+prevents the Modal from unwanted horizontal expansion when a long validation
+text pops up during user's interaction with the form.
+
+👉 Beware of horizontal FormLayout inside `small` modals. While automatic
+overflow handling comes to the rescue in this kind of scenario, you will be
+better off with the combination of auto-sized modal and horizontal FormLayout.
+
 ## Keyboard Control
 
 Modal can be controlled either by mouse or keyboard. To enhance user
@@ -829,24 +826,147 @@ can be closed by pressing the `Escape` key.
 
 To enable it, you just need to pass a reference to the buttons using
 `primaryButtonRef` and `closeButtonRef` props on Modal. The advantage of passing
-a reference to the button is that if the button is disabled, the key press will
-not fire the event.
-
-👉 We strongly recommend using this feature together with Autofocus for a better
-user experience.
+the reference to the button is that if the button is disabled, the key press
+will not fire the event.
 
 ## Autofocus
 
 Autofocus is implemented to enhance the user experience by automatically
-focussing an element within the modal.
+focusing an element within the Modal.
 
 How does it work? It tries to find `input`, `textarea`, and `select` elements
 inside of Modal and moves focus onto the first non-disabled one. If none is
 found and the `primaryButtonRef` prop on Modal is set, then the primary button
-is focused.
+is focused. If there are neither, it tries to focus any other focusable elements.
+In case there are none or `autoFocus` is disabled, Modal itself is focused.
 
-Autofocus is enabled by default, so if you want to control the focus of
-elements manually, set the `autoFocus` prop on Modal to `false`.
+<Playground>
+  {() => {
+    const [modalOpen, setModalOpen] = React.useState(null);
+    const modalPrimaryButtonRef = React.useRef();
+    const modalCloseButtonRef = React.useRef();
+    return (
+      <>
+        <Button
+          label="Launch modal with autofocus and form"
+          onClick={() => setModalOpen(1)}
+        />
+        <Button
+          label="Launch modal with autofocus"
+          onClick={() => setModalOpen(2)}
+        />
+        <Button
+          label="Launch modal with autofocus disabled"
+          onClick={() => setModalOpen(3)}
+        />
+        <div>
+          {modalOpen === 1 && (
+            <Modal
+              closeButtonRef={modalCloseButtonRef}
+              primaryButtonRef={modalPrimaryButtonRef}
+            >
+              <ModalHeader>
+                <ModalTitle>Modal with autoFocus and form</ModalTitle>
+                <ModalCloseButton onClick={() => setModalOpen(null)} />
+              </ModalHeader>
+              <ModalBody>
+                <ModalContent>
+                  <FormLayout autoWidth fieldLayout="horizontal">
+                    <TextField
+                      disabled
+                      label="A form element"
+                    />
+                    <TextField label="Another form element" />
+                    <TextArea label="Yet another one" />
+                  </FormLayout>
+                </ModalContent>
+              </ModalBody>
+              <ModalFooter>
+                <Button
+                  label="Submit"
+                  onClick={() => setModalOpen(null)}
+                  ref={modalPrimaryButtonRef}
+                />
+                <Button
+                  color="secondary"
+                  label="Close"
+                  onClick={() => setModalOpen(null)}
+                  priority="outline"
+                  ref={modalCloseButtonRef}
+                />
+              </ModalFooter>
+            </Modal>
+          )}
+          {modalOpen === 2 && (
+            <Modal
+              closeButtonRef={modalCloseButtonRef}
+              primaryButtonRef={modalPrimaryButtonRef}
+            >
+              <ModalHeader>
+                <ModalTitle>Modal with autoFocus enabled with no form</ModalTitle>
+                <ModalCloseButton onClick={() => setModalOpen(null)} />
+              </ModalHeader>
+              <ModalBody>
+                <ModalContent>
+                  <p>
+                    This Modal autofocuses the primary button or any other
+                    focusable element.
+                  </p>
+                </ModalContent>
+              </ModalBody>
+              <ModalFooter>
+                <Button
+                  label="Acknowledge"
+                  onClick={() => setModalOpen(null)}
+                  ref={modalPrimaryButtonRef}
+                />
+                <Button
+                  color="secondary"
+                  label="Close"
+                  onClick={() => setModalOpen(null)}
+                  priority="outline"
+                  ref={modalCloseButtonRef}
+                />
+              </ModalFooter>
+            </Modal>
+          )}
+          {modalOpen === 3 && (
+            <Modal
+              autoFocus={false}
+              closeButtonRef={modalCloseButtonRef}
+              primaryButtonRef={modalPrimaryButtonRef}
+            >
+              <ModalHeader>
+                <ModalTitle>Modal with autoFocus disabled</ModalTitle>
+              </ModalHeader>
+              <ModalBody>
+                <ModalContent>
+                  <p>
+                    This Modal focuses the Modal element itself.
+                  </p>
+                </ModalContent>
+              </ModalBody>
+              <ModalFooter>
+                <Button
+                  label="Acknowledge"
+                  onClick={() => setModalOpen(null)}
+                  ref={modalPrimaryButtonRef}
+                />
+                <Button
+                  color="secondary"
+                  label="Close"
+                  onClick={() => setModalOpen(null)}
+                  priority="outline"
+                  ref={modalCloseButtonRef}
+                />
+              </ModalFooter>
+            </Modal>
+          )}
+        </div>
+      </>
+    );
+  }}
+</Playground>
 
 ## Scrolling Long Content
 
@@ -948,7 +1068,6 @@ independent of the page itself. This can be done in three ways using the
             setModalScrolling('auto');
             setModalOpen(true);
           }}
-          priority="outline"
         />
         <Button
           label="Launch modal with ScrollView"
@@ -956,7 +1075,6 @@ independent of the page itself. This can be done in three ways using the
             setModalScrolling('custom');
             setModalOpen(true);
           }}
-          priority="outline"
         />
         <Button
           label="Launch modal with non-scrolling body"
@@ -964,12 +1082,11 @@ independent of the page itself. This can be done in three ways using the
             setModalScrolling('none');
             setModalOpen(true);
           }}
-          priority="outline"
         />
         <div>
           {modalOpen && (
             <Modal
-              autoFocus={false}
+              autoFocus={modalScrolling !== 'none'}
               closeButtonRef={modalCloseButtonRef}
               primaryButtonRef={modalPrimaryButtonRef}
               size="small"
@@ -996,6 +1113,7 @@ independent of the page itself. This can be done in three ways using the
                   ref={modalPrimaryButtonRef}
                 />
                 <Button
+                  color="secondary"
                   label="Close"
                   onClick={() => setModalOpen(false)}
                   priority="outline"
@@ -1012,9 +1130,154 @@ independent of the page itself. This can be done in three ways using the
 
 ### Long Content and Autofocus
 
-👉 If you wrap ModalContent with ScrollView, you may want to turn `autoFocus`
-off to prevent the modal from scrolling to the end immediately after being
-opened.
+👉 If you have a Modal with `scrolling` set to `none`, you may want to disable
+`autoFocus` to prevent the modal from scrolling to the end immediately after
+being opened.
+
+## Prevent Scrolling Underneath the Modal
+
+You can choose the mode in which Modal prevents the scroll of the page underneath.
+Default mode prevents scrolling on `<body>` element and accounts for the scrollbar
+width. If you choose `off`, there will be no scroll prevention. If you need more
+flexibility, define your methods `start` (called on Modal's mount) and `reset`
+(called on Modal unmount) wrapped by an object and handle scroll prevention
+yourself.
+
+<Playground>
+  {() => {
+    const [modalOpen, setModalOpen] = React.useState(null);
+    const modalPrimaryButtonRef = React.useRef();
+    const modalCloseButtonRef = React.useRef();
+    const customScrollPreventionObject = {
+      start: () => {
+        // YOUR CUSTOM SCROLL PREVENTING LOGIC GOES HERE
+        window.document.body.style.overflowY = 'hidden'
+      },
+      reset: () => {
+        // YOUR CUSTOM SCROLL RE-ENABLING LOGIC GOES HERE
+        window.document.body.style.overflowY = 'auto'
+      },
+    };
+    return (
+      <>
+        <Button
+          label="Launch modal with default scroll prevention"
+          onClick={() => setModalOpen(1)}
+        />
+        <Button
+          label="Launch modal with no scroll prevention"
+          onClick={() => setModalOpen(2)}
+        />
+        <Button
+          label="Launch modal with custom scroll prevention"
+          onClick={() => setModalOpen(3)}
+        />
+        <div>
+          {modalOpen === 1 && (
+            <Modal
+              closeButtonRef={modalCloseButtonRef}
+              primaryButtonRef={modalPrimaryButtonRef}
+            >
+              <ModalHeader>
+                <ModalTitle>Modal with default scroll prevention</ModalTitle>
+                <ModalCloseButton onClick={() => setModalOpen(null)} />
+              </ModalHeader>
+              <ModalBody>
+                <ModalContent>
+                  <p>
+                    This Modal uses default scroll prevention on the document's
+                    <code>body</code> element.
+                  </p>
+                </ModalContent>
+              </ModalBody>
+              <ModalFooter>
+                <Button
+                  label="Acknowledge"
+                  onClick={() => setModalOpen(null)}
+                  ref={modalPrimaryButtonRef}
+                />
+                <Button
+                  color="secondary"
+                  label="Close"
+                  onClick={() => setModalOpen(null)}
+                  priority="outline"
+                  ref={modalCloseButtonRef}
+                />
+              </ModalFooter>
+            </Modal>
+          )}
+          {modalOpen === 2 && (
+            <Modal
+              closeButtonRef={modalCloseButtonRef}
+              preventScrollUnderneath="off"
+              primaryButtonRef={modalPrimaryButtonRef}
+            >
+              <ModalHeader>
+                <ModalTitle>Modal with no scroll prevention</ModalTitle>
+                <ModalCloseButton onClick={() => setModalOpen(null)} />
+              </ModalHeader>
+              <ModalBody>
+                <ModalContent>
+                  <p>
+                    This Modal does not prevent scrolling.
+                  </p>
+                </ModalContent>
+              </ModalBody>
+              <ModalFooter>
+                <Button
+                  label="Acknowledge"
+                  onClick={() => setModalOpen(null)}
+                  ref={modalPrimaryButtonRef}
+                />
+                <Button
+                  color="secondary"
+                  label="Close"
+                  onClick={() => setModalOpen(null)}
+                  priority="outline"
+                  ref={modalCloseButtonRef}
+                />
+              </ModalFooter>
+            </Modal>
+          )}
+          {modalOpen === 3 && (
+            <Modal
+              closeButtonRef={modalCloseButtonRef}
+              preventScrollUnderneath={customScrollPreventionObject}
+              primaryButtonRef={modalPrimaryButtonRef}
+            >
+              <ModalHeader>
+                <ModalTitle>Modal with custom scroll prevention</ModalTitle>
+                <ModalCloseButton onClick={() => setModalOpen(null)} />
+              </ModalHeader>
+              <ModalBody>
+                <ModalContent>
+                  <p>
+                    This Modal uses provided custom functions to prevent scrolling
+                    and reset it on unmount.
+                  </p>
+                </ModalContent>
+              </ModalBody>
+              <ModalFooter>
+                <Button
+                  label="Acknowledge"
+                  onClick={() => setModalOpen(null)}
+                  ref={modalPrimaryButtonRef}
+                />
+                <Button
+                  color="secondary"
+                  label="Close"
+                  onClick={() => setModalOpen(null)}
+                  priority="outline"
+                  ref={modalCloseButtonRef}
+                />
+              </ModalFooter>
+            </Modal>
+          )}
+        </div>
+      </>
+    );
+  }}
+</Playground>
 
 <!-- markdownlint-disable MD024 -->
 
@@ -1090,6 +1353,7 @@ accessibility.
 | `--rui-Modal--fullscreen__width`                     | Width of fullscreen modal                                     |
 | `--rui-Modal--fullscreen__height`                    | Height of fullscreen modal                                    |
 
+[nng-modal]: https://www.nngroup.com/articles/modal-nonmodal-dialog/
 [React synthetic events]: https://reactjs.org/docs/events.html
 [div]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes
 [heading]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#attributes