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
+23-11Lines changed: 23 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1113,47 +1113,59 @@ root.render(
1113
1113
1114
1114
#### Should I resolve a Promise in a Server or Client Component? {/*resolve-promise-in-server-or-client-component*/}
1115
1115
1116
-
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`.
1116
+
If you have a Promise, at some point you need to unwrap it to read its value. You unwrap it with `await` in a Server Component, and with `use` in a Client Component.
1117
1117
1118
-
Using `await`in a Server Component suspends the Server Component itself, and the Client Component receives the resolved value as a prop:
1118
+
Usually, the simplest option is to `await`the Promise where you create it. The Server Component suspends until the data is ready, and everything below it waits too:
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`:
1128
+
However, you don't have to unwrap it right away. You can pass the Promise down as a prop, and unwrap it deeper in the tree. The component that reads the Promise still suspends, but only that part of the tree waits for the data. Wrap that component in a [`<Suspense>`](/reference/react/Suspense) boundary to show a fallback while the rest of the page renders immediately.
1129
+
1130
+
For example, a deeper Server Component can `await` the Promise it receives:
1130
1131
1131
1132
```js
1133
+
import { Suspense } from'react';
1134
+
1132
1135
// Server Component
1133
1136
exportdefaultfunctionApp() {
1134
-
// Not awaited: starts here, resolves on the client.
Or, in a separate file, a Client Component can unwrap the same Promise with `use`:
1153
+
1140
1154
```js
1141
1155
// Client Component
1142
1156
'use client';
1157
+
1143
1158
import { use } from'react';
1144
1159
1145
1160
exportfunctionMessage({ messagePromise }) {
1146
-
// Will suspend until the data is available.
1147
1161
constmessageContent=use(messagePromise);
1148
1162
return<p>{messageContent}</p>;
1149
1163
}
1150
1164
```
1151
1165
1152
-
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`.
1153
-
1154
-
You can also pass promise as a prop to a Client Component without awaiting it, and then read it with `use(promise)` to suspend deeper in the tree. This allows more of the surrounding UI to complete 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.
1166
+
Passing the Promise down works the same way in both cases. Both suspend where the Promise is read, and both unblock the UI above. The only difference is that Client Components can't `await` during render, so they unwrap the Promise with `use` instead. A common case is interactive content like popovers and tooltips, where the data is only needed after a hover or click.
1155
1167
1156
-
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.
1168
+
See [Revealing content together at once](/reference/react/Suspense#revealing-content-together-at-once) for guidance on where to place Suspense boundaries.
0 commit comments