From 0f92fef974f9efe2b26bab8350241fcd49761471 Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Sat, 27 Jun 2026 22:53:04 +0200 Subject: [PATCH 1/4] [Suspense] Add 'What activates a Suspense boundary' section --- src/content/reference/react/Suspense.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/src/content/reference/react/Suspense.md b/src/content/reference/react/Suspense.md index c2fc0b6ef55..3387957fe41 100644 --- a/src/content/reference/react/Suspense.md +++ b/src/content/reference/react/Suspense.md @@ -203,17 +203,25 @@ async function getAlbums() { - +--- + +### What activates a Suspense boundary {/*what-activates-a-suspense-boundary*/} -**Only Suspense-enabled data sources will activate the Suspense component.** They include: +A Suspense boundary displays its `fallback` while its content is loading, and it can also wait on other resources before revealing that content. The following activate a boundary: -- Data fetching with Suspense-enabled frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/) and [Next.js](https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming#streaming-with-suspense) -- Lazy-loading component code with [`lazy`](/reference/react/lazy) -- Reading the value of a cached Promise with [`use`](/reference/react/use) +- Lazy-loading component code with [`lazy`](/reference/react/lazy). +- Reading a Promise with [`use`](/reference/react/use), including data streamed from [Server Components](/reference/rsc/server-components) and integrations from frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/). +- Loading a stylesheet rendered with [`` and a `precedence` prop.](/reference/react-dom/components/link#special-rendering-behavior) React blocks the boundary until the stylesheet loads, up to a timeout. +- Loading fonts. React blocks a streamed boundary until [`document.fonts.ready`](https://developer.mozilla.org/en-US/docs/Web/API/FontFaceSet/ready) resolves, up to a timeout. Fonts also block a [``](/reference/react/ViewTransition) update. +- Streaming a large boundary's HTML during server rendering. React reveals the content as the HTML arrives. +- Loading an image, where `img.src` blocks the boundary until the source loads. This behavior is not enabled by default. An `` handler opts out, and images in a [``](/reference/react/ViewTransition) update opt in automatically. +- Performing CPU-bound render work inside a `` boundary marked with the `defer` prop. + + Suspense **does not** detect when data is fetched inside an Effect or event handler. -The exact way you would load data in the `Albums` component above depends on your framework. If you use a Suspense-enabled framework, you'll find the details in its data fetching documentation. +The exact way you would load data in the `Albums` component above depends on your framework. If you use a framework with built-in Suspense support, you'll find the details in its data fetching documentation. Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React. From 4ddc1e3fd3fbb8c40affa2a79dcaa15ae3690423 Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Sat, 27 Jun 2026 23:00:25 +0200 Subject: [PATCH 2/4] [Suspense] Clarify image activation wording (review feedback) --- src/content/reference/react/Suspense.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/reference/react/Suspense.md b/src/content/reference/react/Suspense.md index 3387957fe41..ec15a755524 100644 --- a/src/content/reference/react/Suspense.md +++ b/src/content/reference/react/Suspense.md @@ -214,7 +214,7 @@ A Suspense boundary displays its `fallback` while its content is loading, and it - Loading a stylesheet rendered with [`` and a `precedence` prop.](/reference/react-dom/components/link#special-rendering-behavior) React blocks the boundary until the stylesheet loads, up to a timeout. - Loading fonts. React blocks a streamed boundary until [`document.fonts.ready`](https://developer.mozilla.org/en-US/docs/Web/API/FontFaceSet/ready) resolves, up to a timeout. Fonts also block a [``](/reference/react/ViewTransition) update. - Streaming a large boundary's HTML during server rendering. React reveals the content as the HTML arrives. -- Loading an image, where `img.src` blocks the boundary until the source loads. This behavior is not enabled by default. An `` handler opts out, and images in a [``](/reference/react/ViewTransition) update opt in automatically. +- Loading an image, where the `src` blocks the boundary until the image loads. This behavior is not enabled by default. When enabled, an `onLoad` handler opts an image out, and images in a [``](/reference/react/ViewTransition) update opt in automatically. - Performing CPU-bound render work inside a `` boundary marked with the `defer` prop. From 021f94dc847fae905d80f8d9a85f843767ddb41e Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Sat, 27 Jun 2026 23:45:29 +0200 Subject: [PATCH 3/4] Define "suspense-enabled-framework" --- .../reference/react-dom/server/renderToPipeableStream.md | 2 +- .../reference/react-dom/server/renderToReadableStream.md | 2 +- src/content/reference/react/Activity.md | 2 +- src/content/reference/react/Suspense.md | 5 +++-- src/content/reference/react/use.md | 4 ++-- src/content/reference/react/useDeferredValue.md | 2 +- 6 files changed, 9 insertions(+), 8 deletions(-) diff --git a/src/content/reference/react-dom/server/renderToPipeableStream.md b/src/content/reference/react-dom/server/renderToPipeableStream.md index 84b8873a6fd..0ee3acba001 100644 --- a/src/content/reference/react-dom/server/renderToPipeableStream.md +++ b/src/content/reference/react-dom/server/renderToPipeableStream.md @@ -292,7 +292,7 @@ Streaming does not need to wait for React itself to load in the browser, or for Suspense **does not** detect when data is fetched inside an Effect or event handler. -The exact way you would load data in the `Posts` component above depends on your framework. If you use a Suspense-enabled framework, you'll find the details in its data fetching documentation. +The exact way you would load data in the `Posts` component above depends on your framework. If you use a [Suspense-enabled framework](/reference/react/Suspense#what-is-a-suspense-enabled-framework), you'll find the details in its data fetching documentation. Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React. diff --git a/src/content/reference/react-dom/server/renderToReadableStream.md b/src/content/reference/react-dom/server/renderToReadableStream.md index f3e862124af..5c083432a8f 100644 --- a/src/content/reference/react-dom/server/renderToReadableStream.md +++ b/src/content/reference/react-dom/server/renderToReadableStream.md @@ -291,7 +291,7 @@ Streaming does not need to wait for React itself to load in the browser, or for Suspense **does not** detect when data is fetched inside an Effect or event handler. -The exact way you would load data in the `Posts` component above depends on your framework. If you use a Suspense-enabled framework, you'll find the details in its data fetching documentation. +The exact way you would load data in the `Posts` component above depends on your framework. If you use a [Suspense-enabled framework](/reference/react/Suspense#what-is-a-suspense-enabled-framework), you'll find the details in its data fetching documentation. Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React. diff --git a/src/content/reference/react/Activity.md b/src/content/reference/react/Activity.md index 127a4b8d0ae..8027ea9e6d3 100644 --- a/src/content/reference/react/Activity.md +++ b/src/content/reference/react/Activity.md @@ -763,7 +763,7 @@ Pre-rendering components with hidden Activity boundaries is a powerful way to re Activity **does not** detect data that is fetched inside an Effect. -The exact way you would load data in the `Posts` component above depends on your framework. If you use a Suspense-enabled framework, you'll find the details in its data fetching documentation. +The exact way you would load data in the `Posts` component above depends on your framework. If you use a [Suspense-enabled framework](/reference/react/Suspense#what-is-a-suspense-enabled-framework), you'll find the details in its data fetching documentation. Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React. diff --git a/src/content/reference/react/Suspense.md b/src/content/reference/react/Suspense.md index ec15a755524..518e1737a8e 100644 --- a/src/content/reference/react/Suspense.md +++ b/src/content/reference/react/Suspense.md @@ -29,6 +29,7 @@ title: #### Caveats {/*caveats*/} +- Suspense does not detect when data is fetched inside an Effect or event handler. It only activates for the [resources listed below.](#what-activates-a-suspense-boundary) - React does not preserve any state for renders that got suspended before they were able to mount for the first time. When the component has loaded, React will retry rendering the suspended tree from scratch. - If Suspense was displaying content for the tree, but then it suspended again, the `fallback` will be shown again unless the update causing it was caused by [`startTransition`](/reference/react/startTransition) or [`useDeferredValue`](/reference/react/useDeferredValue). - If React needs to hide the already visible content because it suspended again, it will clean up [layout Effects](/reference/react/useLayoutEffect) in the content tree. When the content is ready to be shown again, React will fire the layout Effects again. This ensures that Effects measuring the DOM layout don't try to do this while the content is hidden. @@ -219,9 +220,9 @@ A Suspense boundary displays its `fallback` while its content is loading, and it -Suspense **does not** detect when data is fetched inside an Effect or event handler. +#### What is a Suspense-enabled framework? {/*what-is-a-suspense-enabled-framework*/} -The exact way you would load data in the `Albums` component above depends on your framework. If you use a framework with built-in Suspense support, you'll find the details in its data fetching documentation. +A *Suspense-enabled framework* integrates data fetching with Suspense, so that reading data in a component activates the nearest boundary. The exact way you load data in the `Albums` component above depends on your framework, and you'll find the details in its data fetching documentation. Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React. diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index 1780f82e7b5..c21462d4a3d 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -472,7 +472,7 @@ function Albums() { } ``` -Instead, pass a Promise from a cache, a Suspense-enabled framework, or a Server Component: +Instead, pass a Promise from a cache, a [Suspense-enabled framework](/reference/react/Suspense#what-is-a-suspense-enabled-framework), or a Server Component: ```js // ✅ fetchData reads the Promise from a cache. @@ -538,7 +538,7 @@ The `fetchData` function returns the same Promise each time it's called with the -The way you cache Promises depends on the framework you use with Suspense. Frameworks typically provide built-in caching mechanisms. If you don't use a framework, you can use a simple module-level cache like the one above, or a [Suspense-enabled data source](/reference/react/Suspense#displaying-a-fallback-while-content-is-loading). +The way you cache Promises depends on the framework you use with Suspense. Frameworks typically provide built-in caching mechanisms. If you don't use a framework, you can use a simple module-level cache like the one above, or a [Suspense-enabled data source](/reference/react/Suspense#what-is-a-suspense-enabled-framework). diff --git a/src/content/reference/react/useDeferredValue.md b/src/content/reference/react/useDeferredValue.md index 40cb92629b5..c01250459c5 100644 --- a/src/content/reference/react/useDeferredValue.md +++ b/src/content/reference/react/useDeferredValue.md @@ -86,7 +86,7 @@ During updates, the deferred value will "lag behin -This example assumes you use a Suspense-enabled data source: +This example assumes you use a [Suspense-enabled data source](/reference/react/Suspense#what-is-a-suspense-enabled-framework): - Data fetching with Suspense-enabled frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/) and [Next.js](https://nextjs.org/docs/app/getting-started/fetching-data#with-suspense) - Lazy-loading component code with [`lazy`](/reference/react/lazy) From 14e8f6742fdf91ca7cb483228dc74769b6210f01 Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Sun, 28 Jun 2026 00:14:36 +0200 Subject: [PATCH 4/4] Update outdated framework-less data fetching note to reference use() --- .../reference/react-dom/server/renderToPipeableStream.md | 2 +- .../reference/react-dom/server/renderToReadableStream.md | 2 +- src/content/reference/react-dom/static/prerender.md | 4 ++-- .../reference/react-dom/static/prerenderToNodeStream.md | 4 ++-- src/content/reference/react/Activity.md | 2 +- src/content/reference/react/Suspense.md | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/content/reference/react-dom/server/renderToPipeableStream.md b/src/content/reference/react-dom/server/renderToPipeableStream.md index 0ee3acba001..df148494983 100644 --- a/src/content/reference/react-dom/server/renderToPipeableStream.md +++ b/src/content/reference/react-dom/server/renderToPipeableStream.md @@ -294,7 +294,7 @@ Suspense **does not** detect when data is fetched inside an Effect or event hand The exact way you would load data in the `Posts` component above depends on your framework. If you use a [Suspense-enabled framework](/reference/react/Suspense#what-is-a-suspense-enabled-framework), you'll find the details in its data fetching documentation. -Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React. +Without a framework, you can read a Promise with [`use`](/reference/react/use) as long as the Promise is [cached so the same instance is reused across renders.](/reference/react/use#caching-promises-for-client-components) diff --git a/src/content/reference/react-dom/server/renderToReadableStream.md b/src/content/reference/react-dom/server/renderToReadableStream.md index 5c083432a8f..73019721ab7 100644 --- a/src/content/reference/react-dom/server/renderToReadableStream.md +++ b/src/content/reference/react-dom/server/renderToReadableStream.md @@ -293,7 +293,7 @@ Suspense **does not** detect when data is fetched inside an Effect or event hand The exact way you would load data in the `Posts` component above depends on your framework. If you use a [Suspense-enabled framework](/reference/react/Suspense#what-is-a-suspense-enabled-framework), you'll find the details in its data fetching documentation. -Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React. +Without a framework, you can read a Promise with [`use`](/reference/react/use) as long as the Promise is [cached so the same instance is reused across renders.](/reference/react/use#caching-promises-for-client-components) diff --git a/src/content/reference/react-dom/static/prerender.md b/src/content/reference/react-dom/static/prerender.md index 8ad47aa15f3..8192b491280 100644 --- a/src/content/reference/react-dom/static/prerender.md +++ b/src/content/reference/react-dom/static/prerender.md @@ -283,9 +283,9 @@ Imagine that `` needs to load some data, which takes some time. Ideally Suspense **does not** detect when data is fetched inside an Effect or event handler. -The exact way you would load data in the `Posts` component above depends on your framework. If you use a Suspense-enabled framework, you'll find the details in its data fetching documentation. +The exact way you would load data in the `Posts` component above depends on your framework. If you use a [Suspense-enabled framework](/reference/react/Suspense#what-is-a-suspense-enabled-framework), you'll find the details in its data fetching documentation. -Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React. +Without a framework, you can read a Promise with [`use`](/reference/react/use) as long as the Promise is [cached so the same instance is reused across renders.](/reference/react/use#caching-promises-for-client-components) diff --git a/src/content/reference/react-dom/static/prerenderToNodeStream.md b/src/content/reference/react-dom/static/prerenderToNodeStream.md index 7a31f66a1e4..6336b680bd9 100644 --- a/src/content/reference/react-dom/static/prerenderToNodeStream.md +++ b/src/content/reference/react-dom/static/prerenderToNodeStream.md @@ -284,9 +284,9 @@ Imagine that `` needs to load some data, which takes some time. Ideally Suspense **does not** detect when data is fetched inside an Effect or event handler. -The exact way you would load data in the `Posts` component above depends on your framework. If you use a Suspense-enabled framework, you'll find the details in its data fetching documentation. +The exact way you would load data in the `Posts` component above depends on your framework. If you use a [Suspense-enabled framework](/reference/react/Suspense#what-is-a-suspense-enabled-framework), you'll find the details in its data fetching documentation. -Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React. +Without a framework, you can read a Promise with [`use`](/reference/react/use) as long as the Promise is [cached so the same instance is reused across renders.](/reference/react/use#caching-promises-for-client-components) diff --git a/src/content/reference/react/Activity.md b/src/content/reference/react/Activity.md index 8027ea9e6d3..0ef8dcbef5c 100644 --- a/src/content/reference/react/Activity.md +++ b/src/content/reference/react/Activity.md @@ -765,7 +765,7 @@ Activity **does not** detect data that is fetched inside an Effect. The exact way you would load data in the `Posts` component above depends on your framework. If you use a [Suspense-enabled framework](/reference/react/Suspense#what-is-a-suspense-enabled-framework), you'll find the details in its data fetching documentation. -Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React. +Without a framework, you can read a Promise with [`use`](/reference/react/use) as long as the Promise is [cached so the same instance is reused across renders.](/reference/react/use#caching-promises-for-client-components) diff --git a/src/content/reference/react/Suspense.md b/src/content/reference/react/Suspense.md index 518e1737a8e..a23706f1e79 100644 --- a/src/content/reference/react/Suspense.md +++ b/src/content/reference/react/Suspense.md @@ -224,7 +224,7 @@ A Suspense boundary displays its `fallback` while its content is loading, and it A *Suspense-enabled framework* integrates data fetching with Suspense, so that reading data in a component activates the nearest boundary. The exact way you load data in the `Albums` component above depends on your framework, and you'll find the details in its data fetching documentation. -Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React. +Without a framework, you can read a Promise with [`use`](/reference/react/use) as long as the Promise is [cached so the same instance is reused across renders.](/reference/react/use#caching-promises-for-client-components)