the latest Canary

###  Canary

The ` use ` Hook is currently only available in React’s Canary and
experimental channels. Learn more about [ React’s release channels here
](/community/versioning-policy#all-release-channels) .

` use ` is a React Hook that lets you read the value of a resource like a [
Promise ](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or [ context
](/learn/passing-data-deeply-with-context) .

    
    
    const value = use(resource);

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

* * *

##  Reference

###  ` use(resource) `

Call ` use ` in your component to read the value of a resource like a [
Promise ](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or [ context
](/learn/passing-data-deeply-with-context) .

    
    
    import { use } from 'react';  
    
    
      
    
    
    function MessageComponent({ messagePromise }) {  
    
    
      const message = use(messagePromise);  
    
    
      const theme = use(ThemeContext);  
    
    
      // ...

Unlike all other React Hooks, ` use ` can be called within loops and
conditional statements like ` if ` . Like other React Hooks, the function that
calls ` use ` must be a Component or Hook.

When called with a Promise, the ` use ` Hook integrates with [ ` Suspense `
](/reference/react/Suspense) and [ error boundaries
](/reference/react/Component#catching-rendering-errors-with-an-error-boundary)
. The component calling ` use ` _suspends_ while the Promise passed to ` use `
is pending. If the component that calls ` use ` 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 the ` use ` Hook. If the Promise passed to ` use ` 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 a [ Promise ](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or a [ context ](/learn/passing-data-deeply-with-context) . 

####  Returns

The ` use ` Hook returns the value that was read from the resource like the
resolved value of a [ Promise ](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or [ context
](/learn/passing-data-deeply-with-context) .

####  Caveats

  * The ` use ` Hook must be called inside a Component or a Hook. 
  * When fetching data in a [ Server Component ](/reference/react/use-server) , 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. 
  * Prefer creating Promises in [ Server Components ](/reference/react/use-server) and passing them to [ Client Components ](/reference/react/use-client) 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 with ` use `

When a [ context ](/learn/passing-data-deeply-with-context) is passed to ` use
` , it works similarly to [ ` useContext ` ](/reference/react/useContext) .
While ` useContext ` must be called at the top level of your component, ` use
` can be called inside conditionals like ` if ` and loops like ` for ` . ` use
` is preferred over ` useContext ` because it is more flexible.

    
    
    import { use } from 'react';  
    
    
      
    
    
    function Button() {