From 40ace0551470fcb86d4d3496515b9eac396e4a89 Mon Sep 17 00:00:00 2001
From: Sebastian Sebbie Silbermann <sebastian.silbermann@vercel.com>
Date: Tue, 4 Nov 2025 15:04:29 +0100
Subject: [PATCH 1/5] Docs for Promise subclasses

---
 src/content/reference/react/use.md | 82 ++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md
index dc43fa2289c..6878c152827 100644
--- a/src/content/reference/react/use.md
+++ b/src/content/reference/react/use.md
@@ -436,6 +436,88 @@ To use the Promise's <CodeStep step={1}>`catch`</CodeStep> method, call <CodeSte
 
 ---
 
+### Avoiding fallbacks by passing Promise subclasses {/*avoiding-fallbacks-by-passing-promise-subclasses*/}
+
+React will read the `status` field on Promise subclasses to synchronously read the value without waiting for a microtask. If the Promise is already settled (resolved or rejected), React can read the value immediately without suspending and showing a fallback if the update was not part of a Transition (e.g. [`ReactDOM.flushSync()`](/reference/react-dom/flushSync)).
+
+React will set the `status` field itself if the passed Promise does not have this field set. Suspense-enabled libraries should set the `status` field on the Promises they create to avoid unnecessary fallbacks. Calling `use` conditionally depending on whether a Promise is settled or not is discouraged. `use` should be called unconditionally so that React DevTools can show that the Component may suspend on data.
+
+<Sandpack>
+
+```js src/App.js active
+import { Suspense, use, useState } from "react";
+import { preload } from "./data-fetching.js";
+
+function UserDetails({ userUsable }) {
+  const user = use(userUsable);
+  return <p>Hello, {user}!</p>;
+}
+
+export default function App() {
+  const [userId, setUserId] = useState(null);
+  // The initial
+  const [userUsable, setUser] = useState(null);
+
+  return (
+    <div>
+      <p>
+        Passing the Promise without the <code>status</code> field will show the
+        fallback because the Promise resolves in the next microtask.
+      </p>
+      <button
+        onClick={() => {
+          setUser(Promise.resolve("User #2"));
+          setUserId(2);
+        }}
+      >
+        Load Promise not integrated with Suspense
+      </button>
+      <button
+        onClick={() => {
+          setUser(preload(1));
+          setUserId(1);
+        }}
+      >
+        Load Promise integrated with Suspense
+      </button>
+      <Suspense key={userId} fallback={<p>Loading user...</p>}>
+        {userUsable ? (
+          <UserDetails userUsable={userUsable} />
+        ) : (
+          <p>No user selected</p>
+        )}
+      </Suspense>
+    </div>
+  );
+}
+```
+
+
+```js src/data-fetching.js 
+export function preload(id) {
+  // This is not a real implementation of getting the Promise for the user.
+  // The actual implementation should cache the Promise
+  const promise = Promise.resolve(`User #${id}`);
+
+  // Setting the `status` field allows React to synchronously read
+  // the value if the Promise is already settled by the time the Promise is passed to `use`.
+  promise.status = "pending";
+  promise.then(
+    (value) => {
+      promise.status = "fulfilled";
+      promise.value = value;
+    },
+    (error) => {
+      promise.status = "rejected";
+      promise.reason = error;
+    },
+  );
+  return promise;
+}
+```
+
+</Sandpack>
+
 ## Troubleshooting {/*troubleshooting*/}
 
 ### "Suspense Exception: This is not a real error!" {/*suspense-exception-error*/}

From 12aa604602532568489823a2589824a6e4fd8a7f Mon Sep 17 00:00:00 2001
From: Sebastian Sebbie Silbermann <sebastian.silbermann@vercel.com>
Date: Tue, 4 Nov 2025 19:50:05 +0100
Subject: [PATCH 2/5] Use recipes instead

---
 src/content/reference/react/use.md | 94 +++++++++++++++++++++++++-----
 1 file changed, 79 insertions(+), 15 deletions(-)

diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md
index 6878c152827..4ef4f4d1290 100644
--- a/src/content/reference/react/use.md
+++ b/src/content/reference/react/use.md
@@ -440,13 +440,27 @@ To use the Promise's <CodeStep step={1}>`catch`</CodeStep> method, call <CodeSte
 
 React will read the `status` field on Promise subclasses to synchronously read the value without waiting for a microtask. If the Promise is already settled (resolved or rejected), React can read the value immediately without suspending and showing a fallback if the update was not part of a Transition (e.g. [`ReactDOM.flushSync()`](/reference/react-dom/flushSync)).
 
-React will set the `status` field itself if the passed Promise does not have this field set. Suspense-enabled libraries should set the `status` field on the Promises they create to avoid unnecessary fallbacks. Calling `use` conditionally depending on whether a Promise is settled or not is discouraged. `use` should be called unconditionally so that React DevTools can show that the Component may suspend on data.
+React will set the `status` field itself if the passed Promise does not have this field set. Suspense-enabled libraries should set the `status` field on the Promises they create to avoid unnecessary fallbacks.
+
+Calling `use` conditionally depending on whether a Promise is settled or not is discouraged. `use` should be called unconditionally so that React DevTools can show that the Component may suspend on data.
+
+<Recipes titleText="Difference between setting the status field in your library and not setting the status field" titleId="difference-between-setting-the-status-field-in-your-library-and-not-setting-the-status-field">
+
+#### Passing a basic Promise {/*passing-a-basic-promise*/}
 
 <Sandpack>
 
 ```js src/App.js active
 import { Suspense, use, useState } from "react";
-import { preload } from "./data-fetching.js";
+
+function preloadUser(id) {
+  // This is not a real implementation of getting the Promise for the user.
+  // A real implementation would probably call `fetch` or another data fetching method.
+  // The actual implementation should cache the Promise.
+  const promise = Promise.resolve(`User #${id}`);
+
+  return promise;
+}
 
 function UserDetails({ userUsable }) {
   const user = use(userUsable);
@@ -460,25 +474,21 @@ export default function App() {
 
   return (
     <div>
-      <p>
-        Passing the Promise without the <code>status</code> field will show the
-        fallback because the Promise resolves in the next microtask.
-      </p>
       <button
         onClick={() => {
-          setUser(Promise.resolve("User #2"));
-          setUserId(2);
+          setUser(preloadUser(1));
+          setUserId(1);
         }}
       >
-        Load Promise not integrated with Suspense
+        Load User #1
       </button>
       <button
         onClick={() => {
-          setUser(preload(1));
-          setUserId(1);
+          setUser(preloadUser(2));
+          setUserId(2);
         }}
       >
-        Load Promise integrated with Suspense
+        Load User #2
       </button>
       <Suspense key={userId} fallback={<p>Loading user...</p>}>
         {userUsable ? (
@@ -492,11 +502,22 @@ export default function App() {
 }
 ```
 
+</Sandpack>
+
+<Solution />
 
-```js src/data-fetching.js 
-export function preload(id) {
+#### Passing the Promise with a `status` field {/*passing-the-promise-with-the-status-field*/}
+
+
+<Sandpack>
+
+```js src/App.js active
+import { Suspense, use, useState } from "react";
+
+function preloadUser(id) {
   // This is not a real implementation of getting the Promise for the user.
-  // The actual implementation should cache the Promise
+  // A real implementation would probably call `fetch` or another data fetching method.
+  // The actual implementation should cache the Promise.
   const promise = Promise.resolve(`User #${id}`);
 
   // Setting the `status` field allows React to synchronously read
@@ -514,10 +535,53 @@ export function preload(id) {
   );
   return promise;
 }
+
+function UserDetails({ userUsable }) {
+  const user = use(userUsable);
+  return <p>Hello, {user}!</p>;
+}
+
+export default function App() {
+  const [userId, setUserId] = useState(null);
+  // The initial
+  const [userUsable, setUser] = useState(null);
+
+  return (
+    <div>
+      <button
+        onClick={() => {
+          setUser(preloadUser(1));
+          setUserId(1);
+        }}
+      >
+        Load User #1
+      </button>
+      <button
+        onClick={() => {
+          setUser(preloadUser(2));
+          setUserId(2);
+        }}
+      >
+        Load User #2
+      </button>
+      <Suspense key={userId} fallback={<p>Loading user...</p>}>
+        {userUsable ? (
+          <UserDetails userUsable={userUsable} />
+        ) : (
+          <p>No user selected</p>
+        )}
+      </Suspense>
+    </div>
+  );
+}
 ```
 
 </Sandpack>
 
+<Solution />
+
+</Recipes>
+
 ## Troubleshooting {/*troubleshooting*/}
 
 ### "Suspense Exception: This is not a real error!" {/*suspense-exception-error*/}

From d74a5922231ee677be38d40a6ff25b2d98446445 Mon Sep 17 00:00:00 2001
From: Sebastian Sebbie Silbermann <sebastian.silbermann@vercel.com>
Date: Tue, 4 Nov 2025 20:22:10 +0100
Subject: [PATCH 3/5] target audience

---
 src/content/reference/react/use.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md
index 4ef4f4d1290..027f7442462 100644
--- a/src/content/reference/react/use.md
+++ b/src/content/reference/react/use.md
@@ -438,6 +438,8 @@ To use the Promise's <CodeStep step={1}>`catch`</CodeStep> method, call <CodeSte
 
 ### Avoiding fallbacks by passing Promise subclasses {/*avoiding-fallbacks-by-passing-promise-subclasses*/}
 
+If you are implementing a Suspense-enabled library, you can help React avoid unnecessarily suspending when you know the Promise has already settled, by using `status` and `value` or `reason` fields.
+
 React will read the `status` field on Promise subclasses to synchronously read the value without waiting for a microtask. If the Promise is already settled (resolved or rejected), React can read the value immediately without suspending and showing a fallback if the update was not part of a Transition (e.g. [`ReactDOM.flushSync()`](/reference/react-dom/flushSync)).
 
 React will set the `status` field itself if the passed Promise does not have this field set. Suspense-enabled libraries should set the `status` field on the Promises they create to avoid unnecessary fallbacks.

From cfba52f2cb700aa25ca4b021a37b48d0266f1c18 Mon Sep 17 00:00:00 2001
From: Sebastian Sebbie Silbermann <sebastian.silbermann@vercel.com>
Date: Wed, 5 Nov 2025 09:34:09 +0100
Subject: [PATCH 4/5] Include variant with subclasses

---
 src/content/reference/react/use.md | 132 +++++++++++++++++++++++++++--
 1 file changed, 123 insertions(+), 9 deletions(-)

diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md
index 027f7442462..ed59226e819 100644
--- a/src/content/reference/react/use.md
+++ b/src/content/reference/react/use.md
@@ -440,7 +440,7 @@ To use the Promise's <CodeStep step={1}>`catch`</CodeStep> method, call <CodeSte
 
 If you are implementing a Suspense-enabled library, you can help React avoid unnecessarily suspending when you know the Promise has already settled, by using `status` and `value` or `reason` fields.
 
-React will read the `status` field on Promise subclasses to synchronously read the value without waiting for a microtask. If the Promise is already settled (resolved or rejected), React can read the value immediately without suspending and showing a fallback if the update was not part of a Transition (e.g. [`ReactDOM.flushSync()`](/reference/react-dom/flushSync)).
+React will read the `status` field on the Promise to synchronously read the value without having to wait for a microtask. If the Promise is already settled (resolved or rejected), React can read the value immediately without suspending and showing a fallback if the update was not part of a Transition (e.g. [`ReactDOM.flushSync()`](/reference/react-dom/flushSync)).
 
 React will set the `status` field itself if the passed Promise does not have this field set. Suspense-enabled libraries should set the `status` field on the Promises they create to avoid unnecessary fallbacks.
 
@@ -515,15 +515,116 @@ export default function App() {
 
 ```js src/App.js active
 import { Suspense, use, useState } from "react";
+import { flushSync } from "react-dom";
+
+class PromiseWithStatus extends Promise {
+  status = "pending";
+  value = null;
+  reason = null;
+
+  constructor(executor) {
+    let resolve;
+    let reject;
+    super((_resolve, _reject) => {
+      resolve = _resolve;
+      reject = _reject;
+    });
+    // Setting the `status` field allows React to synchronously read
+    // the value if the Promise is already settled by the time the Promise is
+    // passed to `use`.
+    executor(
+      (value) => {
+        this.status = "fulfilled";
+        this.value = value;
+        resolve(value);
+      },
+      (reason) => {
+        this.status = "rejected";
+        this.reason = reason;
+        reject(reason);
+      }
+    );
+  }
+}
 
 function preloadUser(id) {
   // This is not a real implementation of getting the Promise for the user.
   // A real implementation would probably call `fetch` or another data fetching method.
   // The actual implementation should cache the Promise.
-  const promise = Promise.resolve(`User #${id}`);
+  // The important part is that we are using the PromiseWithStatus subclass here.
+  // Check out the next step if you're not controlling the Promise creation
+  // (e.g. when `fetch` is used).
+  const promise = PromiseWithStatus.resolve(`User #${id}`);
+
+  return promise;
+}
+
+function UserDetails({ userUsable }) {
+  const user = use(userUsable);
+  return <p>Hello, {user}!</p>;
+}
+
+export default function App() {
+  const [userId, setUserId] = useState(null);
+  // The initial
+  const [userUsable, setUser] = useState(null);
 
-  // Setting the `status` field allows React to synchronously read
-  // the value if the Promise is already settled by the time the Promise is passed to `use`.
+  return (
+    <div>
+      <button
+        onClick={() => {
+          // flushSync is only used for illustration purposes.
+          // A real app would probably use startTransition instead.
+          flushSync(() => {
+            setUser(preloadUser(1));
+            setUserId(1);
+          });
+        }}
+      >
+        Load User #1
+      </button>
+      <button
+        onClick={() => {
+          setUser(preloadUser(2));
+          setUserId(2);
+        }}
+      >
+        Load User #2
+      </button>
+      <Suspense key={userId} fallback={<p>Loading user...</p>}>
+        {userUsable ? (
+          <UserDetails userUsable={userUsable} />
+        ) : (
+          <p>No user selected</p>
+        )}
+      </Suspense>
+    </div>
+  );
+}
+
+```
+
+</Sandpack>
+
+<Solution />
+
+#### Simplified implementation setting the `status` field {/*simplified-implementation-setting-the-status-field*/}
+
+<Sandpack>
+
+```js src/App.js active
+import { Suspense, use, useState } from "react";
+import { flushSync } from "react-dom";
+
+function preloadUser(id) {
+  const value = `User #${id}`;
+  // This is not a real implementation of getting the Promise for the user.
+  // A real implementation would probably call `fetch` or another data fetching method.
+  // The actual implementation should cache the Promise.
+  const promise = Promise.resolve(value);
+
+  // We don't need to create a custom subclass.
+  // We can just set the necessary fields directly on the Promise.
   promise.status = "pending";
   promise.then(
     (value) => {
@@ -533,8 +634,15 @@ function preloadUser(id) {
     (error) => {
       promise.status = "rejected";
       promise.reason = error;
-    },
+    }
   );
+
+  // Setting the status in `.then` is too late if we want to create an already
+  // settled Promise. We only included setting the fields in `.then` for
+  // illustration purposes. Since our demo wants an already resolved Promise, 
+  // we set the necessary fields synchronously.
+  promise.status = "fulfilled";
+  promise.value = value;
   return promise;
 }
 
@@ -552,16 +660,22 @@ export default function App() {
     <div>
       <button
         onClick={() => {
-          setUser(preloadUser(1));
-          setUserId(1);
+          // flushSync is only used for illustration purposes.
+          // A real app would probably use startTransition instead.
+          flushSync(() => {
+            setUser(preloadUser(1));
+            setUserId(1);
+          });
         }}
       >
         Load User #1
       </button>
       <button
         onClick={() => {
-          setUser(preloadUser(2));
-          setUserId(2);
+          flushSync(() => {
+            setUser(preloadUser(2));
+            setUserId(2);
+          });
         }}
       >
         Load User #2

From 34997d388833be56b60d402ab0d35edcb0c8fe79 Mon Sep 17 00:00:00 2001
From: Sebastian Sebbie Silbermann <sebastian.silbermann@vercel.com>
Date: Wed, 5 Nov 2025 09:57:12 +0100
Subject: [PATCH 5/5] Avoid scrolling

---
 src/content/reference/react/use.md | 53 +++++++++++++++++-------------
 1 file changed, 31 insertions(+), 22 deletions(-)

diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md
index ed59226e819..ffbb32f5943 100644
--- a/src/content/reference/react/use.md
+++ b/src/content/reference/react/use.md
@@ -456,8 +456,9 @@ Calling `use` conditionally depending on whether a Promise is settled or not is
 import { Suspense, use, useState } from "react";
 
 function preloadUser(id) {
-  // This is not a real implementation of getting the Promise for the user.
-  // A real implementation would probably call `fetch` or another data fetching method.
+  // This is not a real implementation of getting the
+  // Promise for the user. A real implementation would
+  // probably call `fetch` or another data fetching method.
   // The actual implementation should cache the Promise.
   const promise = Promise.resolve(`User #${id}`);
 
@@ -492,7 +493,7 @@ export default function App() {
       >
         Load User #2
       </button>
-      <Suspense key={userId} fallback={<p>Loading user...</p>}>
+      <Suspense key={userId} fallback={<p>Loading</p>}>
         {userUsable ? (
           <UserDetails userUsable={userUsable} />
         ) : (
@@ -529,8 +530,9 @@ class PromiseWithStatus extends Promise {
       resolve = _resolve;
       reject = _reject;
     });
-    // Setting the `status` field allows React to synchronously read
-    // the value if the Promise is already settled by the time the Promise is
+    // Setting the `status` field allows React to
+    // synchronously read the value if the Promise
+    // is already settled by the time the Promise is
     // passed to `use`.
     executor(
       (value) => {
@@ -548,11 +550,13 @@ class PromiseWithStatus extends Promise {
 }
 
 function preloadUser(id) {
-  // This is not a real implementation of getting the Promise for the user.
-  // A real implementation would probably call `fetch` or another data fetching method.
+  // This is not a real implementation of getting the
+  // Promise for the user. A real implementation would
+  // probably call `fetch` or another data fetching method.
   // The actual implementation should cache the Promise.
-  // The important part is that we are using the PromiseWithStatus subclass here.
-  // Check out the next step if you're not controlling the Promise creation
+  // The important part is that we are using the
+  // PromiseWithStatus subclass here. Check out the next
+  // step if you're not controlling the Promise creation
   // (e.g. when `fetch` is used).
   const promise = PromiseWithStatus.resolve(`User #${id}`);
 
@@ -573,8 +577,9 @@ export default function App() {
     <div>
       <button
         onClick={() => {
-          // flushSync is only used for illustration purposes.
-          // A real app would probably use startTransition instead.
+          // flushSync is only used for illustration
+          // purposes. A real app would probably use
+          // startTransition instead.
           flushSync(() => {
             setUser(preloadUser(1));
             setUserId(1);
@@ -591,7 +596,7 @@ export default function App() {
       >
         Load User #2
       </button>
-      <Suspense key={userId} fallback={<p>Loading user...</p>}>
+      <Suspense key={userId} fallback={<p>Loading</p>}>
         {userUsable ? (
           <UserDetails userUsable={userUsable} />
         ) : (
@@ -618,13 +623,15 @@ import { flushSync } from "react-dom";
 
 function preloadUser(id) {
   const value = `User #${id}`;
-  // This is not a real implementation of getting the Promise for the user.
-  // A real implementation would probably call `fetch` or another data fetching method.
+  // This is not a real implementation of getting the
+  // Promise for the user. A real implementation would
+  // probably call `fetch` or another data fetching method.
   // The actual implementation should cache the Promise.
   const promise = Promise.resolve(value);
 
   // We don't need to create a custom subclass.
-  // We can just set the necessary fields directly on the Promise.
+  // We can just set the necessary fields directly on the
+  // Promise.
   promise.status = "pending";
   promise.then(
     (value) => {
@@ -637,10 +644,11 @@ function preloadUser(id) {
     }
   );
 
-  // Setting the status in `.then` is too late if we want to create an already
-  // settled Promise. We only included setting the fields in `.then` for
-  // illustration purposes. Since our demo wants an already resolved Promise, 
-  // we set the necessary fields synchronously.
+  // Setting the status in `.then` is too late if we want
+  // to create an already settled Promise. We only included
+  // setting the fields in `.then` for illustration
+  // purposes. Since our demo wants an already resolved
+  // Promise, we set the necessary fields synchronously.
   promise.status = "fulfilled";
   promise.value = value;
   return promise;
@@ -660,8 +668,9 @@ export default function App() {
     <div>
       <button
         onClick={() => {
-          // flushSync is only used for illustration purposes.
-          // A real app would probably use startTransition instead.
+          // flushSync is only used for illustration
+          // purposes. A real app would probably use
+          // startTransition instead.
           flushSync(() => {
             setUser(preloadUser(1));
             setUserId(1);
@@ -680,7 +689,7 @@ export default function App() {
       >
         Load User #2
       </button>
-      <Suspense key={userId} fallback={<p>Loading user...</p>}>
+      <Suspense key={userId} fallback={<p>Loading</p>}>
         {userUsable ? (
           <UserDetails userUsable={userUsable} />
         ) : (