You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/reference/react/use.md
+11-15Lines changed: 11 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -223,7 +223,7 @@ function Button({ show, children }) {
223
223
224
224
### Reading a Promise from context {/*reading-a-promise-from-context*/}
225
225
226
-
You can pass a Promise through context to share data without prop drilling. Pass the Promise as the context value, then read it with `use(context)` and resolve it with `use(promise)`:
226
+
To share asynchronous data without prop drilling, set a Promise as a context value, then read it with `use(context)` and resolve it with `use(promise)`:
227
227
228
228
```js
229
229
import { use } from'react';
@@ -236,17 +236,9 @@ function Profile() {
236
236
}
237
237
```
238
238
239
-
Wrap the components that read the Promise in a [Suspense](/reference/react/Suspense) boundary so only that subtree suspends while the Promise is pending. See [Usage (Promises)](#usage-promises) below for more on reading Promises with `use`.
240
-
241
-
<Pitfall>
242
-
243
-
Reading a Promise from context comes with trade-offs. Prefer passing the Promise as a [prop](#reading-a-promise-with-use) from a [Server Component](/reference/rsc/server-components) when possible.
244
-
245
-
* **Double unwrap.** Reading the value requires two calls: `use(context)` to get the Promise, then `use(promise)` to get its resolved value. The context value itself is not awaited.
246
-
* **Revalidation scope.** Because the Promise is created in the component that provides it, revalidating the data requires re-rendering that component. Hoisting data into a component high in the tree means everything below it re-renders to update the data.
247
-
* **One Promise per context.** Each piece of data needs its own context. Reaching for more contexts to share more data is usually a sign that the data should be fetched closer to where it's used.
239
+
Reading the value requires two `use` calls because the context value itself isn't awaited. See [Before you use context](/learn/passing-data-deeply-with-context#before-you-use-context) for alternatives to consider before reaching for context.
248
240
249
-
</Pitfall>
241
+
Wrap the components that read the Promise in a [Suspense](/reference/react/Suspense) boundary so only that subtree suspends while the Promise is pending. See [Usage (Promises)](#usage-promises) below for more on reading Promises with `use`.
250
242
251
243
---
252
244
@@ -1110,7 +1102,9 @@ root.render(
1110
1102
1111
1103
#### Should I resolve a Promise in a Server or Client Component? {/*resolve-promise-in-server-or-client-component*/}
1112
1104
1113
-
In general, prefer resolving the Promise with `await` in a Server Component. The Server Component suspends until the Promise resolves, and the Client Component receives the resolved value as a prop:
1105
+
A Promise can be resolved with `await` in a Server Component, or passed as a prop to a Client Component and resolved there with `use`.
1106
+
1107
+
Using `await` in a Server Component suspends the Server Component itself, and the Client Component receives the resolved value as a prop:
1114
1108
1115
1109
```js
1116
1110
// Server Component
@@ -1121,7 +1115,7 @@ export default async function App() {
1121
1115
}
1122
1116
```
1123
1117
1124
-
Resolve the Promise with `use` in a Client Component for data that isn't important for the surrounding UI to render, like below-the-fold content, or content revealed by a hover or click (popovers, tooltips). The Server Component starts the Promise but doesn't await it, so it returns immediately. The Client Component suspends when it calls `use`:
1118
+
A Server Component can also start a Promise without awaiting it and pass the Promise to a Client Component. The Server Component returns immediately, and the Client Component suspends when it calls `use`:
1125
1119
1126
1120
```js
1127
1121
// Server Component
@@ -1144,9 +1138,11 @@ export function Message({ messagePromise }) {
1144
1138
}
1145
1139
```
1146
1140
1147
-
If a Server Component above already awaits the data, pass the resolved value down as a prop instead of creating a new Promise to call `use`.
1141
+
Prefer `await` in a Server Component when possible, since it keeps the data fetching on the server. If a Server Component above already awaits the data, pass the resolved value down as a prop instead of creating a new Promise to call `use`.
1142
+
1143
+
Use `use` in a Client Component to push the data read deeper in the tree, so more of the surrounding UI can render while the Promise is pending. A common case is interactive content like popovers and tooltips, where the data is needed only after a hover or click. Client Components can't `await`, so they rely on `use` to suspend on a Promise.
1148
1144
1149
-
In both cases, wrap the component that reads the Promise in a Suspense boundary so React can display a fallback while the Promise is pending.
1145
+
In either case, wrap the component that reads the Promise in a Suspense boundary so React can show a fallback while the Promise is pending. See [Revealing content together at once](/reference/react/Suspense#revealing-content-together-at-once) for guidance on boundary placement.
0 commit comments