From a8dc1d0a2601d02bce3f55d50aa9bdb2b5106a24 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nikolas=20Schr=C3=B6ter?=
 <nikolas.schroeter@widynski.technology>
Date: Tue, 21 Apr 2026 14:12:22 +0200
Subject: [PATCH] fix: layout shift in s2 modal docs

---
 .gitignore                                    |  1 +
 packages/react-aria-components/docs/Modal.mdx |  8 ++-
 .../stories/Modal.stories.tsx                 | 58 ++++++++++++++++++-
 starters/docs/src/Modal.css                   |  3 +-
 starters/docs/src/Sheet.css                   |  3 +-
 5 files changed, 67 insertions(+), 6 deletions(-)

diff --git a/.gitignore b/.gitignore
index 178fe850797..63448f766af 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,7 @@
 .idea
 .package-lock.json
 .parcel-cache
+.vscode
 build-storybook.log
 coverage
 dist
diff --git a/packages/react-aria-components/docs/Modal.mdx b/packages/react-aria-components/docs/Modal.mdx
index f9e6dbd8210..d17bd684aad 100644
--- a/packages/react-aria-components/docs/Modal.mdx
+++ b/packages/react-aria-components/docs/Modal.mdx
@@ -82,7 +82,7 @@ import {DialogTrigger, Modal, Dialog, Button, Heading, TextField, Label, Input}
   position: absolute;
   top: 0;
   left: 0;
-  width: 100vw;
+  width: var(--page-width);
   height: var(--page-height);
   background: rgba(0 0 0 / .5);
   z-index: 100;
@@ -246,10 +246,11 @@ import {ModalOverlay} from 'react-aria-components';
   position: absolute;
   top: 0;
   left: 0;
-  width: 100%;
+  width: var(--page-width);
   height: var(--page-height);
   background: rgba(45 0 0 / .3);
   backdrop-filter: blur(10px);
+  overflow: clip;
 
   &[data-entering] {
     animation: mymodal-blur 300ms;
@@ -421,11 +422,12 @@ A `Modal` can be targeted with the `.react-aria-Modal` CSS selector, or by overr
 
 By default, `Modal` includes a builtin `ModalOverlay`, which renders a backdrop over the page when a modal is open. This can be targeted using the `.react-aria-ModalOverlay` CSS selector. To customize the `ModalOverlay` with a different class name or other attributes, render a `ModalOverlay` and place a `Modal` inside.
 
-The `--page-height` and `--visual-viewport-height` CSS custom property will be set on the `ModalOverlay`, the latter of which you can use to set the height of the Modal to account for the virtual keyboard on mobile.
+The `--page-height`, `--page-width`, `--visual-viewport-height` and `--visual-viewport-width` CSS custom properties will be set on the `ModalOverlay`, the latter of which you can use to set the size of the Modal to account for the virtual keyboard on mobile.
 
 ```css render=false
 .react-aria-ModalOverlay {
   position: absolute;
+  width: var(--page-width);
   height: var(--page-height);
 }
 
diff --git a/packages/react-aria-components/stories/Modal.stories.tsx b/packages/react-aria-components/stories/Modal.stories.tsx
index 0bb9dd808df..e84ff65d815 100644
--- a/packages/react-aria-components/stories/Modal.stories.tsx
+++ b/packages/react-aria-components/stories/Modal.stories.tsx
@@ -28,7 +28,6 @@ import styles from '../example/index.css';
 import {TextField} from '../src/TextField';
 import './styles.css';
 
-
 export default {
   title: 'React Aria Components/Modal',
   component: Modal
@@ -80,6 +79,63 @@ export const ModalExample: ModalStory = () => (
   </DialogTrigger>
 );
 
+export const SheetExample: ModalStory = () => (
+  <div style={{display: 'flex', flexDirection: 'column'}}>
+    <div style={{display: 'flex', height: '100vh', alignItems: 'center', justifyContent: 'center'}}>
+      <DialogTrigger>
+        <Button>Open modal</Button>
+        <ModalOverlay
+          style={{
+            position: 'fixed',
+            zIndex: 100,
+            top: 0,
+            left: 0,
+            bottom: 0,
+            right: 0,
+            background: 'rgba(0, 0, 0, 0.5)'
+          }}>
+          <Modal
+            style={{
+              position: 'sticky',
+              left: 0,
+              width: '300px',
+              /* Extra padding to account for iOS floating browser UI. */
+              top: '-100px',
+              height: 'calc(100dvh + 200px)',
+              padding: '100px 0',
+              marginLeft: 'auto',
+              background: 'white',
+              outline: 'none',
+              backgroundColor: 'lightgray',
+              borderLeft: '1px solid black',
+              boxShadow: '-8px 0 20px rgba(0, 0, 0, 0.1)',
+              fontFamily: 'system-ui',
+              fontSize: '0.875rem'
+            }}>
+            <Dialog>
+              {({close}) => (
+                <form style={{display: 'flex', flexDirection: 'column'}}>
+                  <Heading slot="title" style={{marginTop: 0}}>Sign up</Heading>
+                  <label>
+                    First Name: <input placeholder="John" />
+                  </label>
+                  <label>
+                    Last Name: <input placeholder="Smith" />
+                  </label>
+                  <Button onPress={close} style={{marginTop: 10}}>
+                    Submit
+                  </Button>
+                </form>
+              )}
+            </Dialog>
+          </Modal>
+        </ModalOverlay>
+      </DialogTrigger>
+    </div>
+    <div style={{height: '100vh'}} />
+  </div>
+);
+
 function InertTest() {
   return (
     <DialogTrigger>
diff --git a/starters/docs/src/Modal.css b/starters/docs/src/Modal.css
index 848e09bb8c7..96db3275429 100644
--- a/starters/docs/src/Modal.css
+++ b/starters/docs/src/Modal.css
@@ -4,9 +4,10 @@
   position: absolute;
   top: 0;
   left: 0;
-  width: 100vw;
+  width: var(--page-width);
   height: var(--page-height);
   background: rgba(0 0 0 / .5);
+  overflow: clip;
   z-index: 100;
   font-family: system-ui;
   font-size: var(--font-size);
diff --git a/starters/docs/src/Sheet.css b/starters/docs/src/Sheet.css
index aa316fb74d1..9d417df9e96 100644
--- a/starters/docs/src/Sheet.css
+++ b/starters/docs/src/Sheet.css
@@ -2,11 +2,12 @@
   position: absolute;
   top: 0;
   left: 0;
-  width: 100%;
+  width: var(--page-width);
   height: var(--page-height);
   background: rgba(0 0 0 / .3);
   backdrop-filter: blur(10px);
   z-index: 100;
+  overflow: clip;
 
   &[data-entering] {
     animation: sheet-blur 300ms;