[WIP] Rewrite `use()` docs by rickhanlonii · Pull Request #8305 · reactjs/react.dev

rickhanlonii · 2026-02-13T18:50:03Z

Preview

cc @samselikoff @gaearon @stephan-noel @aurorascharff @brenelz @MaxwellCohen @hernan-yadiel

github-actions · 2026-02-13T18:52:17Z

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

MaxwellCohen · 2026-02-13T20:14:24Z

src/content/reference/react/use.md

+      <button onClick={handleRefresh} disabled={isPending}>
+        {isPending ? 'Refreshing...' : 'Refresh'}
+      </button>
+      <ErrorBoundary fallback={<p>⚠️Something went wrong</p>}>


This ErrorBoundary does not seem to be working

aurorascharff · 2026-02-13T20:53:44Z

src/content/reference/react/use.md

+async function getAlbums(artistId) {
+  // Add a fake delay to make waiting noticeable.
+  await new Promise(resolve => {
+    setTimeout(resolve, 80);


Is this delay a bit too short? The loading state is very brief in the sandbox. I keep trying to see the loading state in the other two tabs, but the promise resolves too quickly for the difference between hovering/not hovering to be clear.
Trying it in a forked sandbox, 1second seems better.

aurorascharff · 2026-02-13T21:14:31Z

src/content/reference/react/use.md

+
+  function handleRefresh() {
+    startTransition(() => {
+      setAlbumsPromise(fetchData('/the-beatles/albums'));


Adding some artificial delay in fetchData would make the isPending part of the code and the <Suspense fallback={<p>Loading...</p>}> more useful.

However, without async/await, any potential delay on the refresh will not actually disable the button. I added some delay in a forked sandbox, and had to add async await in front of fetchData for it to correctly disable the refresh button. But I guess that would make the error boundary useless?

As Maxwell said, seems like there's a few issues with this example.

MaxwellCohen · 2026-02-13T21:27:23Z

src/content/reference/react/use.md

+```js
+function Albums() {
+  // 🔴 fetch creates a new Promise on every render.
+  const albums = use(fetch('/albums'));


Adding more examples of ways to recreate promises between renders would be helpful, such as some ways you can create a new promise between renders

calling a function that creates a new uncached promise. ie fetch

adding a .then, .catch, .finally on a cached promise

calling an async function

calling functions from the Promise object i.e. Promise.resolve

aurorascharff · 2026-02-13T21:41:42Z

src/content/reference/react/use.md

 }
 ```

 But using `await` in a [Server Component](/reference/rsc/server-components) will block its rendering until the `await` statement is finished. Passing a Promise from a Server Component to a Client Component prevents the Promise from blocking the rendering of the Server Component.


This framing reads a bit like we should always prefer use() over awaiting in a Server Component. It might help to clarify that use() doesn’t inherently avoid blocking and that both approaches still depend on Suspense, and the reason we prefer use() is because we need to use a client component.

Agree! To add to this, the "RSC blocks rendering" framing can read as if it blocks the entire app, when that's not really the case. Maybe we can mention that if we move the async work to a child async Server Component wrapped in <Suspense>, it enables SSR streaming and avoids blocking.

I think this Deep Dive (or somewhere else in these use() docs) would benefit from mentioning the async SC + Suspense pattern and clarifying when each approach is preferable. Also, it's worth noting that neither the Suspense docs nor the RSC docs currently cover this "stremaing SSR" pattern either. Could be a good follow-up to add streaming examples there as well :)

One thing I'm not fully clear on: beyond the bundle size tradeoff, are there other meaningful tradeoffs between the two approaches? Might be worth clarifying that in the Deep Dive as welll

brenelz · 2026-02-14T17:28:11Z

src/content/reference/react/use.md

+
+#### Fetching data with `useEffect` {/*fetching-data-with-useeffect*/}
+
+Without `use`, a common approach is to fetch data in an Effect and update state when the data arrives. This requires managing loading and error states manually, and the component renders empty on first paint before the Effect fires.


would it make sense to mention this isn't recommended and you should use use. Maybe thats obvious

brenelz · 2026-02-14T17:29:30Z

src/content/reference/react/use.md

+
+<Pitfall>
+
+##### Promises passed to `use` must be cached {/*promises-must-cached*/}


I really like this section as I think its a common pitfall

brenelz · 2026-02-14T17:36:15Z

src/content/reference/react/use.md

+    // Set status fields so React can read the value
+    // synchronously if the Promise resolves before
+    // `use` is called (e.g. when preloading on hover).
+    promise.status = 'pending';


interesting hadn't known it was preferred too set the status fields like this

brenelz · 2026-02-14T17:43:33Z

src/content/reference/react/use.md

+```jsx
+function Albums({ albumsPromise }) {
+  try {
+    // ❌ Don't wrap `use` in try-catch


does this trip quite a few people up? Its interesting because its pretty obvious when you know use throws internally. Good callout forsure

brenelz · 2026-02-14T17:44:28Z

Overall looks great. Nice work!

hernan-yadiel · 2026-02-16T00:59:46Z

src/content/reference/react/use.md

+* `promise`: A [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) whose resolved value you want to read. The Promise must be [cached](#caching-promises-for-client-components) so that the same instance is reused across re-renders.

-* The `use` API must be called inside a Component or a Hook.
-* When fetching data in a [Server Component](/reference/rsc/server-components), prefer `async` and `await` over `use`. `async` and `await` pick up rendering from the point where `await` was invoked, whereas `use` re-renders the component after the data is resolved.


I'm curious why this caveat was removed? Is it no longer the preferred way?

I know it could depend of the use case, but I did follow this suggestion as it helps shipping smaller initial bundles, instead of use(dataPromise) where the component where it was called from is still part of the initial bundle.

hernan-yadiel · 2026-02-16T01:14:13Z

src/content/reference/react/use.md

+* `use` must be called inside a Component or a Hook.
+* `use` cannot be called inside a try-catch block. Instead, wrap your component in an [Error Boundary](#displaying-an-error-with-an-error-boundary) to catch the error and display a fallback.
+* Promises passed to `use` must be cached so the same Promise instance is reused across re-renders. [See caching Promises below.](#caching-promises-for-client-components)
+* When passing a Promise from a Server Component to a Client Component, its resolved value must be serializable to pass between server and client. Data types like functions aren't serializable and cannot be the resolved value of such a Promise.


the 'use client' docs has a section with a list of serializable props, we could link to this page

Suggested change

* When passing a Promise from a Server Component to a Client Component, its resolved value must be serializable to pass between server and client. Data types like functions aren't serializable and cannot be the resolved value of such a Promise.

* When passing a Promise from a Server Component to a Client Component, its resolved value must be [serializable](https://react.dev/reference/rsc/use-client#serializable-types) to pass between server and client. Data types like functions aren't serializable and cannot be the resolved value of such a Promise.

[...] to pass between server and client.

nit: for me this phrase feels redundant here, and it reads a bit weird when I first read it. It also subtly shifts from React terminology to infra terminology, which could be confusing since RSC don't necessarily imply a physical server. I would just drop that phrase:

Suggested change

* When passing a Promise from a Server Component to a Client Component, its resolved value must be serializable to pass between server and client. Data types like functions aren't serializable and cannot be the resolved value of such a Promise.

* When passing a Promise from a Server Component to a Client Component, its resolved value must be serializable. Data types like functions aren't serializable and cannot be the resolved value of such a Promise.

rickhanlonii added 2 commits February 13, 2026 13:48

Claude use docs attempt

3725958

Human updates

5fa8c66

meta-cla bot added the CLA Signed label Feb 13, 2026

github-actions bot added the React Core Team label Feb 13, 2026

vercel bot deployed to Preview February 13, 2026 18:51 View deployment

MaxwellCohen reviewed Feb 13, 2026

View reviewed changes

aurorascharff reviewed Feb 13, 2026

View reviewed changes

MaxwellCohen reviewed Feb 13, 2026

View reviewed changes

aurorascharff reviewed Feb 13, 2026

View reviewed changes

brenelz reviewed Feb 14, 2026

View reviewed changes

hernan-yadiel reviewed Feb 16, 2026

View reviewed changes


		#### Fetching data with `useEffect` {/fetching-data-with-useeffect/}

		Without `use`, a common approach is to fetch data in an Effect and update state when the data arrives. This requires managing loading and error states manually, and the component renders empty on first paint before the Effect fires.


		<Pitfall>

		##### Promises passed to `use` must be cached {/promises-must-cached/}

	* When passing a Promise from a Server Component to a Client Component, its resolved value must be serializable to pass between server and client. Data types like functions aren't serializable and cannot be the resolved value of such a Promise.
	* When passing a Promise from a Server Component to a Client Component, its resolved value must be [serializable](https://react.dev/reference/rsc/use-client#serializable-types) to pass between server and client. Data types like functions aren't serializable and cannot be the resolved value of such a Promise.

Conversation

rickhanlonii commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Feb 13, 2026

Size changes

📦 Next.js Bundle Analysis for react-dev

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aurorascharff Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aurorascharff Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brenelz commented Feb 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

rickhanlonii commented Feb 13, 2026 •

edited

Loading

aurorascharff Feb 13, 2026 •

edited

Loading

aurorascharff Feb 13, 2026 •

edited

Loading