The use API

Read a promise's value while rendering

In Suspense, a component read its data with a short line, use(fetchData(…)), and a boundary showed a fallback while it waited. This lesson is about that line. use is a function from React, added in React 19, that reads a value from a resource: a promise or a context. Here it reads an order from a pretend server. The result is live:

1import { Suspense, use } from "react";2import { fetchData } from "./data.js";3 4function OrderStatus() {5  const order = use(fetchData("/orders/42"));6  return <p>Order {order.id}: {order.status}</p>;7}8 9export default function App() {10  return (11    <>12      <h3>Your orders</h3>13      <Suspense fallback={<p>Checking order 42…</p>}>14        <OrderStatus />15      </Suspense>16    </>17  );18}

Line 5 calls fetchData("/orders/42") from the data.js tab. It starts a request and returns a promise: an object that stands for a value that isn't there yet. use takes that promise and gives back its value, the order. Line 6 shows two of the order's fields. Lines 13 to 15 wrap OrderStatus in a Suspense boundary, which shows Checking order 42… until the order arrives, one second later. Press Run again under the result to watch it once more.

Notice what isn't there: no useState for the order, no useEffect to start the request, no if (order === null) check. OrderStatus reads the order as if it were already there, and React takes care of the wait. The data.js tab is the same in every example of this lesson: it answers after a delay with setTimeout, and nothing goes over the network.

What use does while the promise waits

use can't stop JavaScript and wait: a component is a plain function, and it has to return something now. So when the promise is still pending, use suspends the component. It stops the function right there, by throwing a special signal that only React catches, and React shows the nearest Suspense fallback instead. When the promise settles, React calls the component again, from its first line. Two log lines make it visible:

1import { Suspense, use } from "react";2import { fetchData } from "./data.js";3 4function OrderStatus() {5  console.log("OrderStatus starts");6  const order = use(fetchData("/orders/42"));7  console.log(`use gave back: ${order.status}`);8  return <p>Order {order.id}: {order.status}</p>;9}10 11export default function App() {12  return (13    <Suspense fallback={<p>Checking order 42…</p>}>14      <OrderStatus />15    </Suspense>16  );17}

Open the console under the result. At first it shows OrderStatus starts but no use gave back line: line 5 ran, line 6 suspended, and lines 7 and 8 never ran. A second later, both lines appear: React called OrderStatus again, and this time line 6 returned the order straight away. You see each line twice because the preview runs in StrictMode, which renders every component twice in development to catch mistakes.

How does the second call get the value at once? React marks the promise. The first time use sees a promise, React writes status: "pending" on it and adds a callback. When the promise settles, the callback writes status: "fulfilled" and the value (or "rejected" and the reason). On the next call, use reads those fields instead of waiting. Try all three states here:

Read the table row by row: the state of the promise, what use does, and what the reader sees.

The promise must be the same on every render

The Suspense lesson showed a page that waited forever because its component made its promise while rendering. Now you can see why. React calls the component again from its first line, so any promise the component makes is made again too. Here the component calls load from data.js, which starts a new request every time, instead of fetchData:

1import { Suspense, use } from "react";2import { load } from "./data.js";3 4function OrderStatus() {5  // Wrong on purpose: load makes a new promise every time this runs.6  const order = use(load("/orders/42"));7  return <p>Order {order.id}: {order.status}</p>;8}9 10export default function App() {11  return (12    <Suspense fallback={<p>Checking order 42…</p>}>13      <OrderStatus />14    </Suspense>15  );16}

The result says Checking order 42… forever, and the console's count of Load /orders/42 goes up about once a second. Line 6 makes promise A, and use suspends. A second later promise A is fulfilled, and React calls OrderStatus again. Line 6 runs again and makes promise B, which is pending, so use suspends again. The order is loaded over and over and never shown.

This page prints no warning, because each new promise takes a full second. React can only spot the mistake when it tries a component again straight away and gets a different promise than on the first try. That happens when the new promise settles almost at once, like use(fetchData("/orders/42").then((order) => order.status)): the cached order is there, but .then makes a new promise on every render. Then React prints this error in the console: A component was suspended by an uncached promise. Creating promises inside a Client Component or hook is not yet supported, except via a Suspense-compatible library or framework.

In plain words: this promise was made while the component rendered, so React can't keep it between renders. Unless you use a library or framework that supports Suspense, get the promise from a cache. Whether React warns or not, the fix is the same.

The fix is to ask a cache. fetchData (lines 29 to 32 of data.js) keeps each promise in a Map, keyed by its url, and hands back the same promise on every call. Click Add tea after the order shows:

1import { Suspense, use, useState } from "react";2import { fetchData } from "./data.js";3 4function OrderStatus() {5  const order = use(fetchData("/orders/42"));6  return <p>Order {order.id}: {order.status}</p>;7}8 9export default function App() {10  const [cartCount, setCartCount] = useState(0);11  return (12    <>13      <button onClick={() => setCartCount(cartCount + 1)}>Add tea ({cartCount})</button>14      <Suspense fallback={<p>Checking order 42…</p>}>15        <OrderStatus />16      </Suspense>17    </>18  );19}

Line 5 asks the cache, so every render of OrderStatus gets the same promise. Each click on line 13 re-renders App and OrderStatus, but the order stays on screen with no fallback: the promise is already fulfilled, so use returns its value at once. The console shows one Load /orders/42, however many times you click.

Can't a hook keep the promise instead? Not in the component that suspends. A component that suspends before it ever appears on screen hasn't been kept by React yet, so React throws away its state, its refs, and its useMemo, and starts it fresh on the next try:

function OrderStatus() {
  // Wrong on purpose: this component suspends before it ever appears,
  // so React keeps nothing for it, not even this useMemo.
  const promise = useMemo(() => load("/orders/42"), []);
  const order = use(promise);
  return <p>Order {order.id}: {order.status}</p>;
}

This is a piece of a component, not a whole example, so it doesn't run here; the useMemo in the same component button below runs it. Line 4 makes a new promise on every try, just like load on its own. The playground runs OrderStatus with its promise from four places and counts the loads:

Where the promise should come from

The rule from the last section is short: make the promise before the component that reads it renders, or keep it somewhere that outlives that component's renders. Three places work. The first is a cache, like fetchData. The second is an event handler: start the request when the reader clicks, and keep the promise in a parent's state.

1import { Suspense, use, useState } from "react";2import { load } from "./data.js";3 4function Receipt({ receiptPromise }) {5  const receipt = use(receiptPromise);6  return <p>{receipt.items.join(" and ")}: ${receipt.total}</p>;7}8 9export default function App() {10  const [receiptPromise, setReceiptPromise] = useState(null);11  return (12    <>13      <button onClick={() => setReceiptPromise(load("/receipts/42"))}>Show receipt</button>14      {receiptPromise && (15        <Suspense fallback={<p>Loading the receipt…</p>}>16          <Receipt receiptPromise={receiptPromise} />17        </Suspense>18      )}19    </>20  );21}

Line 10 keeps receiptPromise in App's state, starting as null. The click on line 13 calls load once and saves the promise it returns. App never suspends (the boundary on line 15 is below it), so its state survives every render, and Receipt gets the same promise each time through its prop. Line 5 reads it. Click Show receipt: Loading the receipt…, then Tea and Cake: $7. Click it again: the click makes a new promise on purpose, a fresh request, so the fallback shows again for 0.8 seconds.

The third place is the server. In a framework with Server Components, like Next.js, some components run on the server. One of them can start a request and pass the promise down without waiting for it. These two files show the idea; they need a framework, so they don't run here:

// OrderPage.jsx: a Server Component. It runs on the server.
import { Suspense } from "react";
import { db } from "./db.js";
import OrderStatus from "./OrderStatus.jsx";

export default function OrderPage() {
  // Start the request, but don't wait for it.
  const orderPromise = db.orders.find(42);
  return (
    <Suspense fallback={<p>Checking order 42…</p>}>
      <OrderStatus orderPromise={orderPromise} />
    </Suspense>
  );
}

// OrderStatus.jsx: a Client Component. It runs in the browser.
"use client";
import { use } from "react";

export default function OrderStatus({ orderPromise }) {
  const order = use(orderPromise);
  return <p>Order {order.id}: {order.status}</p>;
}

Line 8 of OrderPage.jsx starts the request and keeps the promise, with no await, so the server can send the rest of the page at once. Line 11 passes it to OrderStatus, a Client Component (one that runs in the browser, marked by "use client" on line 2). Line 6 of OrderStatus.jsx reads it with use, and the fallback shows until the server sends the value. A Server Component itself would just await the promise. The Server Components lesson covers them.

Read the table row by row: where the promise is made, whether the next render gets the same one, and when to use it.

A rejected promise goes to an error boundary

Requests fail. When the promise passed to use is rejected, use throws its reason, the error the promise rejected with, just as a throw would. React passes it up to the nearest error boundary: a component that catches errors thrown while its children render and shows a fallback instead. The ErrorBoundary.jsx tab holds a small one; the next lesson explains how it works. The first stock check in data.js fails, like a busy server:

1import { Suspense, use } from "react";2import ErrorBoundary from "./ErrorBoundary.jsx";3import { fetchData } from "./data.js";4 5function Stock() {6  const left = use(fetchData("/stock/cake"));7  return <p>Cake: {left} left</p>;8}9 10export default function App() {11  return (12    <>13      <h3>Carrot cake, $4</h3>14      <ErrorBoundary fallback={(error) => <p>Couldn't check the stock: {error.message}</p>}>15        <Suspense fallback={<p>Checking the stock…</p>}>16          <Stock />17        </Suspense>18      </ErrorBoundary>19    </>20  );21}

Line 6 reads the stock. For 0.6 seconds, the Suspense boundary on line 15 shows Checking the stock…. Then the promise is rejected, use throws, and the ErrorBoundary on line 14 shows its fallback: Couldn't check the stock: The server is busy. Try again. The heading on line 13 stays, because it's outside the boundary. The console shows the error too: by default, React logs every error a boundary catches.

The two boundaries work as a pair. Suspense handles not yet; the error boundary handles never. Put the error boundary outside the Suspense boundary, as lines 14 and 15 do, so one fallback covers the whole part that loads. The practical example below adds a Check again button.

use reads context too, even after an if

The second resource use reads is a context. use(SomeContext) returns the value of the nearest provider above, the same value useContext(SomeContext) returns (Passing data deeply with context covers both). The difference is where you may call it. useContext is a hook, so it has to run at the top of the component, on every render (The rules of hooks). use may run later, inside an if:

1import { createContext, use, useState } from "react";2 3const CurrencyContext = createContext("USD");4 5function Price({ amount, signedIn }) {6  if (!signedIn) {7    return <p>Sign in to see prices.</p>;8  }9  const currency = use(CurrencyContext);10  return <p>Tea: {amount} {currency}</p>;11}12 13export default function App() {14  const [signedIn, setSignedIn] = useState(false);15  return (16    <CurrencyContext value="EUR">17      <button onClick={() => setSignedIn(!signedIn)}>{signedIn ? "Sign out" : "Sign in"}</button>18      <Price amount={3} signedIn={signedIn} />19    </CurrencyContext>20  );21}

Line 3 makes CurrencyContext, and line 16 provides "EUR" to everything inside it. In Price, lines 6 to 8 return early for a shopper who isn't signed in. Only after that does line 9 call use(CurrencyContext). With useContext, line 9 would break the rules of hooks, because it doesn't run on every render. Click Sign in: the price shows as Tea: 3 EUR. Click Sign out and it goes back to the message.

Press Edit & run and change value="EUR" on line 16 to "GBP". After you sign in, the price reads Tea: 3 GBP. Like useContext, use looks for the nearest provider above the component; a provider that Price itself renders wouldn't count.

Where you can and can't call use

use isn't a hook, though its name starts with use. It has its own, shorter list of rules. Read the table row by row: the question, the answer for hooks, and the answer for use.

One place is never allowed: inside try and catch. To suspend, use throws React's signal, and your catch would catch it before React does:

1import { Suspense, use } from "react";2import { fetchData } from "./data.js";3 4function OrderStatus() {5  let status = "unknown";6  try {7    // Wrong on purpose: use must not sit inside try.8    status = use(fetchData("/orders/42")).status;9  } catch {10    status = "unknown";11  }12  return <p>Order 42: {status}</p>;13}14 15export default function App() {16  return (17    <Suspense fallback={<p>Checking order 42…</p>}>18      <OrderStatus />19    </Suspense>20  );21}

The result shows Order 42: unknown straight away and keeps showing it. Line 8 threw the signal, line 9 caught it, and line 10 set unknown, so React never learned it should wait. The console shows React's warning: `use` was called from inside a try/catch block. To handle a failed promise, use an error boundary, as in the last section.

One more rule: always hand the promise to use, even when you think it has settled. Don't read its status field yourself to skip the call. Those fields are React's bookkeeping, and skipping use hides the read from React and its developer tools.

// Wrong: reading the promise's status yourself to skip use.
const order = orderPromise.status === "fulfilled" ? orderPromise.value : use(orderPromise);

// Right: always hand the promise to use, and let React decide.
const order = use(orderPromise);

Line 2 is the wrong version, and line 5 the right one. These lines only show the pattern, so they don't run here. You may call use inside an if that depends on your props or state, as Price did; just don't make the choice depend on the promise itself.

An order page that reads data three ways

Here everything comes together: an order from the cache, a receipt from a click, a currency read only when needed, and a stock check that fails once and can be retried. Watch the result: the stock check fails first, then the order arrives.

1import { Suspense, createContext, use, useState } from "react";2import ErrorBoundary from "./ErrorBoundary.jsx";3import { fetchData, load, refetchData } from "./data.js";4 5const CurrencyContext = createContext("USD");6 7function OrderStatus() {8  const order = use(fetchData("/orders/42"));9  return <p>Order {order.id}: {order.status}</p>;10}11 12function Receipt({ receiptPromise, showTotal }) {13  const receipt = use(receiptPromise);14  let total = "";15  if (showTotal) {16    const currency = use(CurrencyContext);17    total = ` (${receipt.total} ${currency})`;18  }19  return <p>Receipt: {receipt.items.join(" and ")}{total}</p>;20}21 22function Stock() {23  const left = use(fetchData("/stock/cake"));24  return <p>Cake: {left} left</p>;25}26 27export default function App() {28  const [receiptPromise, setReceiptPromise] = useState(null);29  const [stockTries, setStockTries] = useState(1);30 31  function checkStockAgain() {32    refetchData("/stock/cake");33    setStockTries(stockTries + 1);34  }35 36  return (37    <CurrencyContext value="EUR">38      <Suspense fallback={<p>Checking order 42…</p>}>39        <OrderStatus />40      </Suspense>41      <button onClick={() => setReceiptPromise(load("/receipts/42"))}>Show receipt</button>42      {receiptPromise && (43        <Suspense fallback={<p>Loading the receipt…</p>}>44          <Receipt receiptPromise={receiptPromise} showTotal={true} />45        </Suspense>46      )}47      <ErrorBoundary48        key={stockTries}49        fallback={(error) => (50          <p>51            {error.message} <button onClick={checkStockAgain}>Check again</button>52          </p>53        )}54      >55        <Suspense fallback={<p>Checking the stock…</p>}>56          <Stock />57        </Suspense>58      </ErrorBoundary>59    </CurrencyContext>60  );61}

• Line 8: OrderStatus reads the order from the cache, inside its own boundary (lines 38 to 40).
• Lines 12 to 20: Receipt reads the promise from its prop, then reads the currency with use inside the if on line 15. The click on line 41 makes that promise.
• Line 23: Stock reads the stock from the cache. The first answer is a failure, so the ErrorBoundary on lines 47 to 58 shows the message and a Check again button.
• Lines 31 to 34: checkStockAgain drops the failed promise from the cache with refetchData and adds one to stockTries. That number is the boundary's key on line 48, so React replaces the boundary with a fresh one, its error forgotten (Preserving and resetting state explains keys). Stock renders again, gets a new promise, and this time the server answers Cake: 3 left.

Click Check again, then Show receipt. The receipt line ends with (7 EUR), the total in the currency from line 37.

Common mix-ups

• "use is a hook, so the rules of hooks apply." No. use can be called inside if, loops, and after an early return. It still runs only while a component or hook renders, and never inside try.
• "use waits for the promise, like await." No. It can't pause the function. It stops it, React shows a fallback, and React calls the component again from the top once the promise settles.
• "I can create the promise right where I call use." No. A promise made while rendering is new on every render, so the fallback never goes away. Get it from a cache, a parent's state, or a Server Component.
• "useMemo or useState in the same component keeps the promise." No. A component that suspends before it first appears is thrown away and started fresh, hooks and all. Keep the promise above it.
• "Wrap use in try/catch to handle a failed request." No. That catches React's signal and breaks the wait. Put an error boundary around the component instead.
• "use replaces Suspense." No. They work together: use suspends, and the nearest Suspense boundary decides what shows meanwhile.

Practice exercises

Each exercise has a live result: click in it, change the code with Edit & run, and open the console to see what data.js loads.

1import { Suspense, use, useState } from "react";2import { fetchData } from "./data.js";3 4function OrderStatus() {5  const order = use(fetchData("/orders/42"));6  return <p>Order {order.id}: {order.status}</p>;7}8 9export default function App() {10  const [cartCount, setCartCount] = useState(0);11  return (12    <>13      <button onClick={() => setCartCount(cartCount + 1)}>Add tea ({cartCount})</button>14      <Suspense fallback={<p>Checking order 42…</p>}>15        <OrderStatus />16      </Suspense>17    </>18  );19}

1import { Suspense, use, useState } from "react";2import { fetchData } from "./data.js";3 4function OrderStatus() {5  const order = use(fetchData("/orders/42"));6  return <p>Order {order.id}: {order.status}</p>;7}8 9export default function App() {10  const [cartCount, setCartCount] = useState(0);11  return (12    <>13      <button onClick={() => setCartCount(cartCount + 1)}>Add tea ({cartCount})</button>14      <Suspense fallback={<p>Checking order 42…</p>}>15        <OrderStatus />16      </Suspense>17    </>18  );19}

1import { use } from "react";2import { fetchData } from "./data.js";3 4function OrderStatus() {5  const order = use(fetchData("/orders/42"));6  return <p>Order {order.id}: {order.status}</p>;7}8 9export default function App() {10  return (11    <>12      <h3>Your orders</h3>13      <OrderStatus />14    </>15  );16}

1import { Suspense, use } from "react";2import { fetchData } from "./data.js";3 4function OrderStatus() {5  const order = use(fetchData("/orders/42"));6  return <p>Order {order.id}: {order.status}</p>;7}8 9export default function App() {10  return (11    <>12      <h3>Your orders</h3>13      <Suspense fallback={<p>Checking order 42…</p>}>14        <OrderStatus />15      </Suspense>16    </>17  );18}

1import { Suspense, use } from "react";2import { load } from "./data.js";3 4function Receipt() {5  const receipt = use(load("/receipts/42"));6  return <p>{receipt.items.join(" and ")}: ${receipt.total}</p>;7}8 9export default function App() {10  return (11    <Suspense fallback={<p>Loading the receipt…</p>}>12      <Receipt />13    </Suspense>14  );15}

1import { Suspense, use } from "react";2import { fetchData } from "./data.js";3 4function Receipt() {5  const receipt = use(fetchData("/receipts/42"));6  return <p>{receipt.items.join(" and ")}: ${receipt.total}</p>;7}8 9export default function App() {10  return (11    <Suspense fallback={<p>Loading the receipt…</p>}>12      <Receipt />13    </Suspense>14  );15}

1import { createContext, use } from "react";2 3const CurrencyContext = createContext("USD");4 5function Price({ name, amount, signedIn }) {6  if (!signedIn) {7    return <p>{name}: sign in to see the price.</p>;8  }9  // Read the currency here, and show it after the amount.10  return <p>{name}: {amount}</p>;11}12 13export default function App() {14  return (15    <CurrencyContext value="GBP">16      <Price name="Tea" amount={3} signedIn={true} />17      <Price name="Cake" amount={4} signedIn={false} />18    </CurrencyContext>19  );20}

1import { createContext, use } from "react";2 3const CurrencyContext = createContext("USD");4 5function Price({ name, amount, signedIn }) {6  if (!signedIn) {7    return <p>{name}: sign in to see the price.</p>;8  }9  const currency = use(CurrencyContext);10  return <p>{name}: {amount} {currency}</p>;11}12 13export default function App() {14  return (15    <CurrencyContext value="GBP">16      <Price name="Tea" amount={3} signedIn={true} />17      <Price name="Cake" amount={4} signedIn={false} />18    </CurrencyContext>19  );20}

1import { Suspense, use, useState } from "react";2import { fetchData } from "./data.js";3 4function Receipt() {5  const receipt = use(fetchData("/receipts/42"));6  return <p>{receipt.items.join(" and ")}: ${receipt.total}</p>;7}8 9export default function App() {10  const [open, setOpen] = useState(false);11  return (12    <>13      <button onClick={() => setOpen(true)}>Show receipt</button>14      {open && (15        <Suspense fallback={<p>Loading the receipt…</p>}>16          <Receipt />17        </Suspense>18      )}19    </>20  );21}

1import { Suspense, use, useState } from "react";2import { fetchData } from "./data.js";3 4function Receipt() {5  const receipt = use(fetchData("/receipts/42"));6  return <p>{receipt.items.join(" and ")}: ${receipt.total}</p>;7}8 9export default function App() {10  const [open, setOpen] = useState(false);11  return (12    <>13      <button14        onMouseEnter={() => fetchData("/receipts/42")}15        onClick={() => setOpen(true)}16      >17        Show receipt18      </button>19      {open && (20        <Suspense fallback={<p>Loading the receipt…</p>}>21          <Receipt />22        </Suspense>23      )}24    </>25  );26}

1import { Suspense, use } from "react";2import ErrorBoundary from "./ErrorBoundary.jsx";3import { fetchData } from "./data.js";4 5function Stock() {6  const left = use(fetchData("/stock/cake"));7  return <p>Cake: {left} left</p>;8}9 10export default function App() {11  return (12    <>13      <h3>Carrot cake, $4</h3>14      <Suspense fallback={<p>Checking the stock…</p>}>15        <Stock />16      </Suspense>17    </>18  );19}

1import { Suspense, use } from "react";2import ErrorBoundary from "./ErrorBoundary.jsx";3import { fetchData } from "./data.js";4 5function Stock() {6  const left = use(fetchData("/stock/cake"));7  return <p>Cake: {left} left</p>;8}9 10export default function App() {11  return (12    <>13      <h3>Carrot cake, $4</h3>14      <ErrorBoundary fallback={() => <p>Stock unknown. You can still order.</p>}>15        <Suspense fallback={<p>Checking the stock…</p>}>16          <Stock />17        </Suspense>18      </ErrorBoundary>19    </>20  );21}

Check your understanding

Key takeaways

• use(promise) returns the value of a fulfilled promise, suspends while it's pending, and throws if it's rejected.
• A Suspense boundary shows a fallback while the component waits; an error boundary shows one if the promise is rejected.
• After a promise settles, React calls the component again from the top, so the promise must be the same one: from a cache, a parent's state, or a Server Component.
• A promise made in render, even inside useMemo in the component that suspends, is new each time and never shows.
• use(context) reads the nearest provider, like useContext, but may run after an early return or inside an if.
• Call use only while rendering, never inside try, and never skip it by reading the promise's status.

Coming next: Error boundaries. It shows how to write the ErrorBoundary this lesson borrowed, what it can and can't catch, how to retry, and how to report errors.