Skip to content

[Suspense] Document what activates a boundary, with live examples #8505

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aurorascharff merged 29 commits into from
Jul 9, 2026
Merged

[Suspense] Document what activates a boundary, with live examples #8505

Changes from 1 commit
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
0f92fef
[Suspense] Add 'What activates a Suspense boundary' section
aurorascharff Jun 27, 2026
4ddc1e3
[Suspense] Clarify image activation wording (review feedback)
aurorascharff Jun 27, 2026
021f94d
Define "suspense-enabled-framework"
aurorascharff Jun 27, 2026
14e8f67
Update outdated framework-less data fetching note to reference use()
aurorascharff Jun 27, 2026
d34d3ce
fix: clarify Suspense boundary activation and fallback behavior
aurorascharff Jun 30, 2026
2e01ae7
Add code example
aurorascharff Jun 30, 2026
f6d28e6
update styling
aurorascharff Jun 30, 2026
16fa091
Cleanup caveat
aurorascharff Jun 30, 2026
54958a7
add link to blogpost
aurorascharff Jun 30, 2026
6f6185d
Replace notes with link to suspense docs
aurorascharff Jul 1, 2026
b7c2094
Tweak caveat
aurorascharff Jul 1, 2026
201b5e3
Update caveat to clarify streaming behavior during server rendering
aurorascharff Jul 1, 2026
d2df82a
Address feedback
aurorascharff Jul 2, 2026
b33c637
address feedback
aurorascharff Jul 2, 2026
9091bee
Clarify documentation on Suspense-enabled frameworks
aurorascharff Jul 2, 2026
9be6345
Update links and wording
aurorascharff Jul 2, 2026
025ee7a
Improve example
aurorascharff Jul 3, 2026
2dfe10f
Clarify heading for Suspense-enabled frameworks section
aurorascharff Jul 3, 2026
567cdd4
Restructure page
aurorascharff Jul 5, 2026
c45c9b0
Update to be docs compliant and clarify images
aurorascharff Jul 6, 2026
1ed5be2
Address review feedback
aurorascharff Jul 8, 2026
3eb0f38
Add more suspense examples
aurorascharff Jul 8, 2026
dd5449e
Merge branch 'suspense-what-activates' of github.com:aurorascharff/re…
aurorascharff Jul 8, 2026
d63cade
Add more examples
aurorascharff Jul 8, 2026
d56099a
Clarify image loading behavior during <ViewTransition> updates in Sus…
aurorascharff Jul 8, 2026
2942718
Enhance Suspense documentation with additional details on font and im…
aurorascharff Jul 8, 2026
551cdf6
Update
aurorascharff Jul 9, 2026
0d41392
Enhance Suspense documentation with examples of stylesheet loading be…
aurorascharff Jul 9, 2026
5cc4a30
agent review
aurorascharff Jul 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 14 additions & 6 deletions src/content/reference/react/Suspense.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,17 +203,25 @@ async function getAlbums() {

</Sandpack>

<Note>
---

### What activates a Suspense boundary {/*what-activates-a-suspense-boundary*/}

@MaxwellCohen MaxwellCohen Jun 27, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very excited to see these being called out and updated!

My understanding is that a "suspense enabled framework" is a framework that wraps these features that activates a suspense boundaries . If that is true could we specifically call it out what suspense enabled means?

@aurorascharff aurorascharff Jun 27, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe this? 021f94d


**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:
Comment thread
eps1lon marked this conversation as resolved.
Outdated

- 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 [`<link rel="stylesheet">` 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 [`<ViewTransition>`](/reference/react/ViewTransition) update.
Comment thread
aurorascharff marked this conversation as resolved.
Outdated
- Streaming a large boundary's HTML during server rendering. React reveals the content as the HTML arrives.

@eps1lon eps1lon Jun 29, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The other examples are probably self-explanatory. This one could do with an example. Examples for all would be nice with a side-by-side with a Suspense implementation that wouldn't block (e.g. with just some simple DOM operations).

@aurorascharff aurorascharff Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about with effect as an example? It's a common confusion

CleanShot 2026-06-30 at 11 46 52@2x

@eps1lon eps1lon Jul 1, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's for use() vs fetching in an Effect though. I was thinking about a boundary with a lot of text. There are sandboxes in the prerender docs (or resume. Can't remember but we do have one example for PPR in the docs) that show how to build sandboxes showing streaming SSR.

@aurorascharff aurorascharff Jul 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. I must have misunderstood. I'm wondering if the example you are referring to is too low level for the suspense page, but would fit nicely in the prerender or resume docs. I also think keeping this current example is quite a nice way to show this common misconception. I've added now a link to those docs here, we can add the example on that page? 201b5e3 possibly in a follow-up PR

@eps1lon eps1lon Jul 2, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's any SSR API with support for streaming. The whole point for me was to explain Suspense in a single place. It isn't low-level because it explains how React thinks about Suspense.

@aurorascharff aurorascharff Jul 2, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh, gotcha, will add!

@aurorascharff aurorascharff Jul 2, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

d2df82a

So I simplified my example. Still open to removing the whole use affecting if we don't think it's necessary, and then I added your example.

- Loading an image, where `img.src` blocks the boundary until the source loads. This behavior is not enabled by default. An `<img onLoad>` handler opts out, and images in a [`<ViewTransition>`](/reference/react/ViewTransition) update opt in automatically.
Comment thread
aurorascharff marked this conversation as resolved.
Outdated
- <ExperimentalBadge /> Performing CPU-bound render work inside a `<Suspense>` boundary marked with the `defer` prop.

<Note>

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.

@MaxwellCohen MaxwellCohen Jun 27, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line is out of date because of yours and @rickhanlonii great work on the use() docs.

@aurorascharff aurorascharff Jun 27, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice catch!!! Updating!


Expand Down
Loading