use

constvalue =use(resource);

• Reference
  • use(resource)
• Usage
  • Reading context withuse
  • Streaming data from the server to the client
  • Dealing with rejected Promises
• Troubleshooting
  • “Suspense Exception: This is not a real error!”

Reference

use(resource)

Calluse in your component to read the value of a resource like aPromise orcontext.

import{use}from'react';

functionMessageComponent({messagePromise}){
constmessage =use(messagePromise);
consttheme =use(ThemeContext);
// ...

Unlike React Hooks,use can be called within loops and conditional statements likeif. Like React Hooks, the function that callsuse must be a Component or Hook.

When called with a Promise, theuse API integrates withSuspense andError Boundaries. The component callingusesuspends while the Promise passed touse is pending. If the component that callsuse is wrapped in a Suspense boundary, the fallback will be displayed. Once the Promise is resolved, the Suspense fallback is replaced by the rendered components using the data returned by theuse API. If the Promise passed touse is rejected, the fallback of the nearest Error Boundary will be displayed.

See more examples below.

Parameters

• resource: this is the source of the data you want to read a value from. A resource can be aPromise or acontext.

Returns

Theuse API returns the value that was read from the resource like the resolved value of aPromise orcontext.

Caveats

• Theuse API must be called inside a Component or a Hook.
• When fetching data in aServer Component, preferasync andawait overuse.async andawait pick up rendering from the point whereawait was invoked, whereasuse re-renders the component after the data is resolved.
• Prefer creating Promises inServer Components and passing them toClient Components over creating Promises in Client Components. Promises created in Client Components are recreated on every render. Promises passed from a Server Component to a Client Component are stable across re-renders.See this example.

Usage

Reading context withuse

When acontext is passed touse, it works similarly touseContext. WhileuseContext must be called at the top level of your component,use can be called inside conditionals likeif and loops likefor.use is preferred overuseContext because it is more flexible.

import{use}from'react';

functionButton(){
consttheme =use(ThemeContext);
// ...

use returns thecontext value for thecontext you passed. To determine the context value, React searches the component tree and findsthe closest context provider above for that particular context.

To pass context to aButton, wrap it or one of its parent components into the corresponding context provider.

functionMyPage(){
return(
<ThemeContextvalue="dark">
<Form/>
</ThemeContext>
);
}

functionForm(){
// ... renders buttons inside ...
}

It doesn’t matter how many layers of components there are between the provider and theButton. When aButtonanywhere inside ofForm callsuse(ThemeContext), it will receive"dark" as the value.

UnlikeuseContext,use can be called in conditionals and loops likeif.

functionHorizontalRule({show}){
if(show){
consttheme =use(ThemeContext);
return<hrclassName={theme}/>;
}
returnfalse;
}

use is called from inside aif statement, allowing you to conditionally read values from a Context.

Streaming data from the server to the client

Data can be streamed from the server to the client by passing a Promise as a prop from aServer Component to aClient Component.

import{fetchMessage}from'./lib.js';
import{Message}from'./message.js';

exportdefaultfunctionApp(){
constmessagePromise =fetchMessage();
return(
<Suspensefallback={<p>waiting for message...</p>}>
<MessagemessagePromise={messagePromise}/>
</Suspense>
);
}

TheClient Component then takesthe Promise it received as a prop and passes it to theuse API. This allows theClient Component to read the value fromthe Promise that was initially created by the Server Component.

// message.js
'use client';

import{use}from'react';

exportfunctionMessage({messagePromise}){
constmessageContent =use(messagePromise);
return<p>Here is the message:{messageContent}</p>;
}

BecauseMessage is wrapped inSuspense, the fallback will be displayed until the Promise is resolved. When the Promise is resolved, the value will be read by theuse API and theMessage component will replace the Suspense fallback.

exportdefaultasyncfunctionApp(){
constmessageContent =awaitfetchMessage();
return<MessagemessageContent={messageContent}/>
}

Dealing with rejected Promises

In some cases a Promise passed touse could be rejected. You can handle rejected Promises by either:

1. Displaying an error to users with an Error Boundary.
2. Providing an alternative value withPromise.catch

Displaying an error to users with an Error Boundary

If you’d like to display an error to your users when a Promise is rejected, you can use anError Boundary. To use an Error Boundary, wrap the component where you are calling theuse API in an Error Boundary. If the Promise passed touse is rejected the fallback for the Error Boundary will be displayed.

Providing an alternative value withPromise.catch

If you’d like to provide an alternative value when the Promise passed touse is rejected you can use the Promise’scatch method.

import{Message}from'./message.js';

exportdefaultfunctionApp(){
constmessagePromise =newPromise((resolve,reject)=>{
reject();
}).catch(()=>{
return"no new message found.";
});

return(
<Suspensefallback={<p>waiting for message...</p>}>
<MessagemessagePromise={messagePromise}/>
</Suspense>
);
}

To use the Promise’scatch method, callcatch on the Promise object.catch takes a single argument: a function that takes an error message as an argument. Whatever isreturned by the function passed tocatch will be used as the resolved value of the Promise.

Troubleshooting

“Suspense Exception: This is not a real error!”

You are either callinguse outside of a React Component or Hook function, or callinguse in a try–catch block. If you are callinguse inside a try–catch block, wrap your component in an Error Boundary, or call the Promise’scatch to catch the error and resolve the Promise with another value.See these examples.

If you are callinguse outside a React Component or Hook function, move theuse call to a React Component or Hook function.

functionMessageComponent({messagePromise}){
functiondownload(){
// ❌ the function calling `use` is not a Component or Hook
constmessage =use(messagePromise);
// ...

Instead, calluse outside any component closures, where the function that callsuse is a Component or Hook.

functionMessageComponent({messagePromise}){
// ✅ `use` is being called from a component.
constmessage =use(messagePromise);
// ...