Concurrent rendering, Suspense and transitions inside

A render React starts, drops, and starts again

The work loop lesson showed that a transition renders in slices of about 5 ms. This lesson shows what happens when something else needs the main thread in the middle of that render. Press Refresh the list in the shop below, and read the log under it.

1import { memo, startTransition, useLayoutEffect, useRef, useState } from "react";2import { clearLog, note, whenRowsStart } from "./log.js";3 4function busy(ms) {5  const end = performance.now() + ms;6  while (performance.now() < end) {}7}8 9function TeaRow({ n }) {10  busy(2); // a slow row: 2 ms of work11  note(`row ${n}`);12  return <li>Tea {n + 1}</li>;13}14 15const TeaList = memo(function TeaList({ list }) {16  note(`render TeaList, list ${list}`);17  useLayoutEffect(() => note(`commit TeaList, list ${list}`), [list]);18  const rows = Array.from({ length: 40 }, (_, n) => <TeaRow key={n} n={n} />);19  return <ol>{rows}</ol>;20});21 22export default function App() {23  const [list, setList] = useState(1);24  const [cart, setCart] = useState(0);25  const addButton = useRef(null);26  note(`render App: list ${list}, cart ${cart}`);27 28  function refresh() {29    clearLog();30    startTransition(() => setList(list + 1));31    // A shopper clicks Add to cart while the new list renders.32    whenRowsStart(() => addButton.current.click());33  }34 35  return (36    <>37      <button onClick={refresh}>Refresh the list</button>38      <button ref={addButton} onClick={() => setCart(cart + 1)}>39        Add to cart ({cart})40      </button>41      <TeaList list={list} />42    </>43  );44}

Each of the 40 rows does 2 ms of busy work on line 10 and writes row n to the log on line 11. The log.js tab keeps the log: lines 5 to 22 there join rows into ranges and keep one line when StrictMode calls a component twice. Line 30 refreshes the list in a transition. Line 32 uses whenRowsStart, lines 33 to 37 of log.js, to click Add to cart the first time the browser gets a turn after a row has rendered: a shopper clicking while the new list renders. Read the log from the top:

1. render App: list 2, cart 0, render TeaList, list 2, then row 0 (on some computers rows 0 to 1). The transition starts list 2 and gets one or two rows in.
2. render App: list 1, cart 1. The click's render. Its cart is 1, but its list is 1: the transition's update isn't part of this render. TeaList doesn't log, because memo skips it when its list prop is the same.
3. render App: list 2, cart 1, render TeaList, list 2, rows 0 to 39. The transition again. It doesn't go on from row 1. It starts again at the top, and renders row 0 a second time.
4. commit TeaList, list 2. Only this last attempt reaches the page.

So React built part of a new list, dropped it to handle a click, and built it again from the start. Nothing on the page showed the half-built list. That is what concurrent rendering means in React: a render is a draft that React can build in pieces, set aside, or throw away, and only a finished draft is committed. This lesson reads the code in ReactFiberWorkLoop.js that makes each of those choices, then the same choices for Suspense, useDeferredValue and useSyncExternalStore.

Pausing keeps the draft

Each slice of a transition is a call to renderRootConcurrent. The first thing it decides is whether this slice goes on with the draft it has, in ReactFiberWorkLoop.js, lines 2785 to 2814:

// If the root or lanes have changed, throw out the existing stack
// and prepare a fresh one. Otherwise we'll continue where we left off.
if (workInProgressRoot !== root || workInProgressRootRenderLanes !== lanes) {
  // ... (DevTools bookkeeping left out)
  resetRenderTimer();
  prepareFreshStack(root, lanes);
} else {
  // This is a continuation of an existing work-in-progress.
  //
  // If we were previously in prerendering mode, check if we received any new
  // data during an interleaved event.
  workInProgressRootIsPrerendering = checkIfRootIsPrerendering(root, lanes);
}

1. Line 3 compares two variables of the work loop with this call's arguments. workInProgressRoot is the root the draft is for, and workInProgressRootRenderLanes the lanes, the bits that say which updates the draft includes.
2. Lines 5 and 6: something is different, so prepareFreshStack starts a new draft at the root. That's the first slice of every render, and the restart you saw in the overview.
3. Lines 7 to 13: the same root and the same lanes. Nothing is reset, so the loop goes on from workInProgress, the fiber where the last slice stopped. (Line 12 is about prerendering, which the suspending section comes back to.)

Watch a pause that isn't a restart. This list has 12 rows of 1 ms each, and line 27 asks log.js to add a line every time the browser gets a turn. Press Refresh the list.

1import { memo, startTransition, useLayoutEffect, useState } from "react";2import { clearLog, note, noteBrowserTurns } from "./log.js";3 4function busy(ms) {5  const end = performance.now() + ms;6  while (performance.now() < end) {}7}8 9function TeaRow({ n }) {10  busy(1); // 1 ms of work11  note(`row ${n}`);12  return <li>Tea {n + 1}</li>;13}14 15const TeaList = memo(function TeaList({ list }) {16  note(`render TeaList, list ${list}`);17  useLayoutEffect(() => note(`commit TeaList, list ${list}`), [list]);18  return <ol>{Array.from({ length: 12 }, (_, n) => <TeaRow key={n} n={n} />)}</ol>;19});20 21export default function App() {22  const [list, setList] = useState(1);23 24  function refresh() {25    clearLog();26    startTransition(() => setList(list + 1));27    noteBrowserTurns();28  }29 30  return (31    <>32      <button onClick={refresh}>Refresh the list</button>33      <TeaList list={list} />34    </>35  );36}

The log reads something like rows 0 to 2, the browser's turn, rows 3 to 5, the browser's turn, and so on to commit TeaList, list 2. Each row takes about 2 ms (1 ms, twice in StrictMode), so a 5 ms slice holds two or three rows. After each turn, the next slice starts at the next row, never back at row 0: the lanes didn't change, so line 3 of the excerpt was false every time. The exact ranges depend on your computer.

An urgent update throws the draft away

Back to the overview. The click on Add to cart reached React's listener on the root, which gives a click SyncLane, the most urgent lane. (The event system lesson follows the click there.) React then schedules the root again, in a microtask, in ReactFiberRootScheduler.js, lines 442 to 456:

if (
  includesSyncLane(nextLanes) &&
  // If we're prerendering, then we should use the concurrent work loop
  // even if the lanes are synchronous, so that prerendering never blocks
  // the main thread.
  !checkIfRootIsPrerendering(root, nextLanes)
) {
  // Synchronous work is always flushed at the end of the microtask, so we
  // don't need to schedule an additional task.
  if (existingCallbackNode !== null) {
    cancelCallback(existingCallbackNode);
  }
  root.callbackPriority = SyncLane;
  root.callbackNode = null;
  return SyncLane;

Line 2: the root's next lanes include SyncLane. Lines 10 to 12 cancel the scheduler task that would have run the transition's next slice, and line 15 says the work is sync: React renders it at the end of this microtask, before the browser does anything else. Which lanes are "next" comes from getNextLanes, and its last check decides whether a render in progress may be dropped, in ReactFiberLane.js, lines 334 to 358:

// If we're already in the middle of a render, switching lanes will interrupt
// it and we'll lose our progress. We should only do this if the new lanes are
// higher priority.
if (
  wipLanes !== NoLanes &&
  wipLanes !== nextLanes &&
  // If we already suspended with a delay, then interrupting is fine. Don't
  // bother waiting until the root is complete.
  (wipLanes & suspendedLanes) === NoLanes
) {
  const nextLane = getHighestPriorityLane(nextLanes);
  const wipLane = getHighestPriorityLane(wipLanes);
  if (
    // Tests whether the next lane is equal or lower priority than the wip
    // one. This works because the bits decrease in priority as you go left.
    nextLane >= wipLane ||
    // Default priority updates should not interrupt transition updates. The
    // only difference between default updates and transition updates is that
    // default updates do not support refresh transitions.
    (nextLane === DefaultLane && (wipLane & TransitionLanes) !== NoLanes)
  ) {
    // Keep working on the existing in-progress tree. Do not interrupt.
    return wipLanes;
  }
}

1. Lines 4 to 10: a render is in progress (wipLanes), and the lanes waiting are different ones.
2. Lines 11 and 12 take the most urgent lane of each. Lanes are bits, and a smaller bit is more urgent: SyncLane is 2, InputContinuousLane 8, DefaultLane 32, and the first transition lane 256.
3. Line 16: if the waiting lane is the same or less urgent, keep working. Line 20 adds one more case: DefaultLane, the lane of a timer or a fetch result, doesn't interrupt a transition either.
4. Line 23 returns the lanes in progress, so the draft survives. Only a more urgent lane gets past this check.

For the click, performWorkOnRoot renders SyncLane with renderRootSync, whose first lines compare the lanes the same way. They differ, so it calls prepareFreshStack, which begins at lines 2254 to 2258:

resetWorkInProgressStack();
workInProgressRoot = root;
const rootWorkInProgress = createWorkInProgress(root.current, null);
workInProgress = rootWorkInProgress;
workInProgressRootRenderLanes = lanes;

Line 1 throws the old draft away. Lines 2 to 5 start a new one from root.current, the tree on the page, for the click's lanes. Here is line 1's function, resetWorkInProgressStack:

function resetWorkInProgressStack() {
  if (workInProgress === null) return;
  let interruptedWork;
  if (workInProgressSuspendedReason === NotSuspended) {
    // Normal case. Work-in-progress hasn't started yet. Unwind all
    // its parents.
    interruptedWork = workInProgress.return;
  } else {
    // Work-in-progress is in suspended state. Reset the work loop and unwind
    // both the suspended fiber and all its parents.
    resetSuspendedWorkLoopOnUnwind(workInProgress);
    interruptedWork = workInProgress;
  }
  while (interruptedWork !== null) {
    const current = interruptedWork.alternate;
    unwindInterruptedWork(
      current,
      interruptedWork,
      workInProgressRootRenderLanes,
    );
    interruptedWork = interruptedWork.return;
  }
  workInProgress = null;
}

1. Line 2: no draft, nothing to do.
2. Lines 4 to 13 pick where to start unwinding: the parent of the fiber the loop would have begun next, or the fiber itself if it was waiting on data.
3. Lines 14 to 22 climb through return to the root. unwindInterruptedWork undoes what each begun fiber pushed while rendering, such as the context values it provided, so the next render starts clean.
4. Line 23 sets workInProgress to null. The draft's fibers aren't on the page, and nothing points at them now. The rows it rendered are simply lost.

The click's render and commit come next. The transition's lane is still pending on the root, so the commit schedules a new task, and its first renderRootConcurrent has no draft: back to prepareFreshStack and the root. Step through the overview's log with the functions that run for each line:

Now test getNextLanes' rule with four kinds of update. Each button refreshes the list, and when the rows start, sends one update to the cart: a click on Add to cart (line 35), a mousemove event on the cart badge (line 36), a plain setCart from the timer (line 37), or a setCart in another transition (line 38).

1import { memo, startTransition, useLayoutEffect, useRef, useState } from "react";2import { clearLog, note, whenRowsStart } from "./log.js";3 4function busy(ms) {5  const end = performance.now() + ms;6  while (performance.now() < end) {}7}8 9function TeaRow({ n }) {10  busy(2); // a slow row: 2 ms of work11  note(`row ${n}`);12  return <li>Tea {n + 1}</li>;13}14 15const TeaList = memo(function TeaList({ list }) {16  note(`render TeaList, list ${list}`);17  useLayoutEffect(() => note(`commit TeaList, list ${list}`), [list]);18  const rows = Array.from({ length: 40 }, (_, n) => <TeaRow key={n} n={n} />);19  return <ol>{rows}</ol>;20});21 22export default function App() {23  const [list, setList] = useState(1);24  const [cart, setCart] = useState(0);25  const addButton = useRef(null);26  const badge = useRef(null);27  note(`render App: list ${list}, cart ${cart}`);28 29  function refreshThen(update) {30    clearLog();31    startTransition(() => setList(list + 1));32    whenRowsStart(update);33  }34 35  const click = () => addButton.current.click();36  const mouseMove = () => badge.current.dispatchEvent(new MouseEvent("mousemove", { bubbles: true }));37  const timer = () => setCart((n) => n + 1);38  const transition = () => startTransition(() => setCart((n) => n + 1));39 40  return (41    <>42      <p>43        Refresh the list, and meanwhile:{" "}44        <button onClick={() => refreshThen(click)}>a click</button>45        <button onClick={() => refreshThen(mouseMove)}>a mouse move</button>46        <button onClick={() => refreshThen(timer)}>a timer</button>47        <button onClick={() => refreshThen(transition)}>a transition</button>48      </p>49      <button ref={addButton} onClick={() => setCart(cart + 1)}>Add to cart</button>50      <span ref={badge} onMouseMove={() => setCart((n) => n + 1)}> Cart: {cart}</span>51      <TeaList list={list} />52    </>53  );54}

After a click and a mouse move, the log shows rows 0 to 39 after a second render TeaList: the draft was thrown away. After a timer and a transition, it shows rows 0 to 39 once, then commit TeaList, and only then the cart's render. The transition kept going, and the cart waited until the whole list was done. How to read the table: each row is an update that arrives while a transition renders.

A component that waits throws

A render can also stop because a component needs data that hasn't arrived. This product page reads reviews with use inside a Suspense boundary. The api.js tab returns one promise per product, which resolves after 800 ms. Watch the log as the page loads, then click Black tea.

1import { Suspense, use, useLayoutEffect, useState } from "react";2import { clearLog, note } from "./log.js";3import { fetchReviews } from "./api.js";4 5function Reviews({ product }) {6  const promise = fetchReviews(product);7  note(`render Reviews ${product}: status ${promise.status ?? "not set"}`);8  const reviews = use(promise);9  useLayoutEffect(() => note(`commit Reviews ${product}`), [product]);10  return <ul>{reviews.map((review) => <li key={review}>{review}</li>)}</ul>;11}12 13function Loading() {14  useLayoutEffect(() => note("commit Loading"), []);15  return <p>Loading reviews...</p>;16}17 18const products = ["Green tea", "Black tea", "Mint tea"];19 20export default function App() {21  const [product, setProduct] = useState("Green tea");22  note(`render App: ${product}`);23 24  function show(next) {25    clearLog();26    setProduct(next);27  }28 29  return (30    <>31      {products.map((name) => (32        <button key={name} onClick={() => show(name)} aria-pressed={name === product}>33          {name}34        </button>35      ))}36      <Suspense fallback={<Loading />}>37        <Reviews product={product} />38      </Suspense>39    </>40  );41}

Line 7 logs the promise's status field just before line 8 calls use. A plain promise has no such field, so the first line says status not set. Then commit Loading: the fallback. Then the same component renders again with status pending. Someone set that field. When the reviews arrive, Reviews renders with status fulfilled and commits. Here is who sets it, trackUsedThenable, which use calls, in ReactFiberThenable.js:

switch (thenable.status) {
  case 'fulfilled': {
    // ... (comments left out)
    const fulfilledValue: T = thenable.value;
    return fulfilledValue;
  }
    // ... (the rejected case, and a promise React has seen before, left out)
    const pendingThenable: PendingThenable<T> = thenable as any;
    pendingThenable.status = 'pending';
    pendingThenable.then(
      fulfilledValue => {
        if (thenable.status === 'pending') {
          const fulfilledThenable: FulfilledThenable<T> = thenable as any;
          fulfilledThenable.status = 'fulfilled';
          fulfilledThenable.value = fulfilledValue;
        }
      },
    // ... (the same for a rejected promise, and a last check for one that already settled, left out)
    suspendedThenable = thenable;
    // ... (development-only warnings left out)
    throw SuspenseException;

1. Lines 1 to 6: a promise React already marked fulfilled gives its value straight away. That's why the last render of Reviews didn't suspend.
2. Lines 8 to 17: a promise with no status gets status = 'pending', and a then callback that writes 'fulfilled' and the value onto the promise when it resolves. React adds these fields to your promise object.
3. Lines 19 and 21: still pending, so React remembers the promise in suspendedThenable and throws SuspenseException, a special error, not the promise. Throwing stops your component in the middle, at line 8 of the example.

The work loop catches it. handleThrow gets the promise back with getSuspendedThenable, and throwException looks for the nearest Suspense boundary, in ReactFiberThrow.js:

// Mark the nearest Suspense boundary to switch to rendering a fallback.
const suspenseBoundary = getSuspenseHandler();
if (suspenseBoundary !== null) {
  // ... (the switch on the boundary's kind left out)
  if (getShellBoundary() === null) {
    // Suspended in the "shell" of the app. This is an undesirable
    // loading state. We should avoid committing this tree.
    renderDidSuspendDelayIfPossible();
  // ... (the other branch, and the code that marks the boundary to show its fallback, left out)
  const retryQueue: RetryQueue | null =
    suspenseBoundary.updateQueue as any;
  if (retryQueue === null) {
    suspenseBoundary.updateQueue = new Set([wakeable]);
  } else {
    retryQueue.add(wakeable);
  }
  // ... (comments left out)
  if (disableLegacyMode || suspenseBoundary.mode & ConcurrentMode) {
    attachPingListener(root, wakeable, rootRenderLanes);
  }

1. Lines 1 to 3: getSuspenseHandler returns the closest Suspense boundary above the component, here the one on line 36 of the example.
2. Lines 5 to 8 note when a fallback here would hide content already on the page. For a click, React commits the fallback anyway; the next section shows what a transition does with this note.
3. Lines 10 to 16 add the promise to the boundary's updateQueue, its retry queue. When the fallback commits, React puts a listener on each promise there; when one resolves, a retry renders the boundary again, at a retry lane.
4. Lines 18 to 20: attachPingListener also calls the promise's then. When it resolves, the root is pinged: its lanes are marked as worth trying again.

For a click, the boundary then switches to its fallback, and the render commits it: commit Loading. The line status pending comes right after. In React 19, after showing a fallback, React renders the suspended part again at once, without committing, to start any other data it will need. React's code calls this prerendering, and it's the "show the fallback first" behavior from the Suspense lesson. When the reviews arrive, the retry renders only the boundary and what's inside it. There is no render App line before status fulfilled.

A transition that suspends keeps the old screen

The same page, with the product chosen in a transition. Click Black tea and read the log.

1import { Suspense, use, useLayoutEffect, useState, useTransition } from "react";2import { clearLog, note } from "./log.js";3import { fetchReviews } from "./api.js";4 5function Reviews({ product }) {6  const promise = fetchReviews(product);7  note(`render Reviews ${product}: status ${promise.status ?? "not set"}`);8  const reviews = use(promise);9  useLayoutEffect(() => note(`commit Reviews ${product}`), [product]);10  return <ul>{reviews.map((review) => <li key={review}>{review}</li>)}</ul>;11}12 13function Loading() {14  useLayoutEffect(() => note("commit Loading"), []);15  return <p>Loading reviews...</p>;16}17 18const products = ["Green tea", "Black tea", "Mint tea"];19 20export default function App() {21  const [product, setProduct] = useState("Green tea");22  const [isPending, startTransition] = useTransition();23  note(`render App: ${product}${isPending ? " (pending)" : ""}`);24 25  function show(next) {26    clearLog();27    startTransition(() => setProduct(next));28  }29 30  return (31    <>32      {products.map((name) => (33        <button key={name} onClick={() => show(name)} aria-pressed={name === product}>34          {name}35        </button>36      ))}37      <div style={{ opacity: isPending ? 0.5 : 1 }}>38        <Suspense fallback={<Loading />}>39          <Reviews product={product} />40        </Suspense>41      </div>42    </>43  );44}

Line 27 switches the product in a transition, and line 37 dims the old reviews while isPending is true. There is no commit Loading this time. The log reads:

1. render App: Green tea (pending) and render Reviews Green tea: an urgent render that only sets isPending, committed at once.
2. render App: Black tea and render Reviews Black tea: status not set: the transition. Reviews suspends, and nothing is committed. The Green tea reviews stay, dimmed.
3. reviews for Black tea arrive, then render App: Black tea again: the whole transition renders again from the root, Reviews reads status fulfilled, and commit Reviews Black tea.

The difference is in throwException's lines 5 to 8: getShellBoundary() === null. React calls the part of the page that is already showing content the shell. While it renders a Suspense boundary, it records one as the shell boundary only when that boundary isn't showing content, in ReactFiberSuspenseContext.js, lines 89 to 101:

if (shellBoundary === null) {
  if (current === null || isCurrentTreeHidden()) {
    // This boundary is not visible in the current UI.
    shellBoundary = handler;
  } else {
    const prevState: SuspenseState = current.memoizedState;
    // $FlowFixMe[invalid-compare]
    if (prevState !== null) {
      // This boundary is showing a fallback in the current UI.
      shellBoundary = handler;
    }
  }
}

Line 2: a new boundary (no current fiber) or a hidden one. Line 8: one already showing its fallback. Either way, a fallback there hides nothing the user can see now. Our boundary shows Green tea's reviews, so shellBoundary stays null, and throwException calls renderDidSuspendDelayIfPossible, which sets the render's result to RootSuspendedWithDelay. When the render ends, finishConcurrentRender reads that result:

case RootSuspendedWithDelay: {
  if (!includesOnlyTransitions(lanes) && !includesOnlyRetries(lanes)) {
    // Commit the placeholder.
    break;
  }
}
// Fallthrough
case RootSuspendedAtTheShell: {
  // This is a transition, so we should exit without committing a
  // placeholder and without scheduling a timeout. Delay indefinitely
  // until we receive more data.
  // ... (profiling left out)
  const didAttemptEntireTree = !workInProgressRootDidSkipSuspendedSiblings;
  markRootSuspended(
    root,
    lanes,
    workInProgressDeferredLane,
    didAttemptEntireTree,
  );
  return;
}

1. Lines 2 to 5: for an urgent lane, break goes on to the commit, fallback and all.
2. Lines 8 to 21: for a transition, the comment says it: exit without committing. markRootSuspended notes that these lanes are waiting for data, and line 20 returns. The finished draft is never committed.

When the reviews arrive, the ping listener from throwException runs pingSuspendedRoot:

function pingSuspendedRoot(
  root: FiberRoot,
  wakeable: Wakeable,
  pingedLanes: Lanes,
) {
  const pingCache = root.pingCache;
  if (pingCache !== null) {
    // The wakeable resolved, so we no longer need to memoize, because it will
    // never be thrown again.
    pingCache.delete(wakeable);
  }

  markRootPinged(root, pingedLanes);
  // ... (profiling, and a restart check for a render that is still running, left out)
  ensureRootIsScheduled(root);
}

Line 13, markRootPinged, marks the waiting lanes as pinged, and line 15 schedules the root. getNextLanes picks pinged lanes even though they suspended, so the transition renders again from prepareFreshStack, and this time use finds status fulfilled.

Try the other branch. Press Edit & run and change line 38 to <Suspense key={product} fallback={<Loading />}>. The key makes each product a new boundary, which has no current fiber, so it becomes the shell boundary. Click Mint tea: the log shows commit Loading even in a transition. How to read the table: each row asks one question of both versions of the page.

useDeferredValue: an urgent render, then a deferred one

useDeferredValue uses the same machinery without any startTransition in your code. Type g in the box below.

1import { memo, useDeferredValue, useLayoutEffect, useState } from "react";2import { note } from "./log.js";3 4function busy(ms) {5  const end = performance.now() + ms;6  while (performance.now() < end) {}7}8 9function TeaRow({ n }) {10  busy(2); // a slow row: 2 ms of work11  note(`row ${n}`);12  return <li>Tea {n + 1}</li>;13}14 15const Results = memo(function Results({ query }) {16  note(`render Results "${query}"`);17  useLayoutEffect(() => note(`commit Results "${query}"`), [query]);18  return <ol>{Array.from({ length: 30 }, (_, n) => <TeaRow key={n} n={n} />)}</ol>;19});20 21export default function App() {22  const [query, setQuery] = useState("");23  const deferredQuery = useDeferredValue(query);24  note(`render App: query "${query}", deferred "${deferredQuery}"`);25 26  return (27    <>28      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Search teas" />29      <Results query={deferredQuery} />30    </>31  );32}

The log shows render App: query "g", deferred "", then render App: query "g", deferred "g", render Results "g", the rows, and commit Results "g". Line 23 returned the old value in the first render and the new value in the second. It decides in ReactFiberHooks.js, lines 3082 to 3107:

const shouldDeferValue =
  !includesOnlyNonUrgentLanes(renderLanes) && !isRenderingDeferredWork();
if (shouldDeferValue) {
  // This is an urgent update. Since the value has changed, keep using the
  // previous value and spawn a deferred render to update it later.

  // Schedule a deferred render
  const deferredLane = requestDeferredLane();
  currentlyRenderingFiber.lanes = mergeLanes(
    currentlyRenderingFiber.lanes,
    deferredLane,
  );
  markSkippedUpdateLanes(deferredLane);

  // Reuse the previous value. We do not need to mark this as an update,
  // because we did not render a new value.
  return prevValue;
} else {
  // This is not an urgent update, so we can use the latest value regardless
  // of what it is. No need to defer it.

  // Mark this as an update to prevent the fiber from bailing out.
  markWorkInProgressReceivedUpdate();
  hook.memoizedState = value;
  return value;
}

1. Lines 1 and 2: defer only in an urgent render (your key gave SyncLane), and not in the deferred render itself.
2. Line 8: requestDeferredLane picks a transition lane for the second render. Lines 9 to 12 put that lane on this fiber, so the root has more work after this commit.
3. Line 17 returns prevValue, the value from the last commit, which the hook keeps in its memoizedState. Results gets the same prop, and memo skips it, so the urgent render is fast.
4. Lines 18 to 26: in the deferred render, the new value is returned and saved.

The deferred render has a transition lane, so everything from the interrupting section applies. Type gre quickly: the log shows a render Results "gr" that gets only a row or two before the next key's render App: query "gre", deferred "g". The key's SyncLane threw the deferred draft away, and the urgent render returned "g", the last committed value, not "gr".

Tearing, and the render useSyncExternalStore repeats

A pause between slices is a gap where other code runs. The external stores lesson showed what goes wrong when that code changes data React reads while rendering: tearing, one screen showing two versions of the same data. Here the store.js tab keeps a price, and line 30 raises it when the rows start. Click Show prices.

1import { startTransition, useLayoutEffect, useState, useSyncExternalStore } from "react";2import { clearLog, note, whenRowsStart } from "./log.js";3import { getPrice, raisePrice, subscribe } from "./store.js";4 5function busy(ms) {6  const end = performance.now() + ms;7  while (performance.now() < end) {}8}9 10function PriceRow({ n }) {11  busy(4); // a slow row12  const price = useSyncExternalStore(subscribe, getPrice);13  note(`row ${n} reads $${price}`);14  return <li>Tea {n + 1}: ${price}</li>;15}16 17function PriceList() {18  note("render PriceList");19  useLayoutEffect(() => note("commit PriceList"), []);20  return <ol>{[0, 1, 2, 3, 4, 5].map((n) => <PriceRow key={n} n={n} />)}</ol>;21}22 23export default function App() {24  const [shown, setShown] = useState(false);25 26  function showPrices() {27    clearLog();28    startTransition(() => setShown(true));29    // The price changes while the rows render.30    whenRowsStart(raisePrice);31  }32 33  return (34    <>35      <button onClick={showPrices} disabled={shown}>Show prices</button>36      {shown && <PriceList />}37    </>38  );39}

The log shows row 0 reads $3, the price changes to $4, rows 1 to 5 reading $4, and then render PriceList a second time, with every row reading $4, before commit PriceList. The page shows $4 six times. The first render was finished and torn, and React rendered it again before committing. The rows read the price with useSyncExternalStore on line 12, which, while mounting, does this in ReactFiberHooks.js:

// Unless we're rendering a blocking lane, schedule a consistency check.
// Right before committing, we will walk the tree and check if any of the
// stores were mutated.
// ... (hydration notes and a sanity check left out)
const rootRenderLanes = getWorkInProgressRootRenderLanes();
if (!includesBlockingLane(rootRenderLanes)) {
  pushStoreConsistencyCheck(fiber, getSnapshot, nextSnapshot);
}

Line 6: a render that isn't blocking, that is, one that can pause. Line 7 notes the store's getSnapshot and the value this row read, on the fiber. After the render, performWorkOnRoot checks every note, in lines 1222 to 1244:

const finishedWork: Fiber = root.current.alternate as any;
if (
  renderWasConcurrent &&
  !isRenderConsistentWithExternalStores(finishedWork)
) {
  // ... (profiling left out)
  // A store was mutated in an interleaved event. Render again,
  // synchronously, to block further mutations.
  exitStatus = renderRootSync(root, lanes, false);
  // We assume the tree is now consistent because we didn't yield to any
  // concurrent events.
  renderWasConcurrent = false;
  // Need to check the exit status again.
  continue;
}

1. Lines 2 to 5: if the render was sliced, isRenderConsistentWithExternalStores walks the finished tree and calls each noted getSnapshot again. Row 0 read 3, and getPrice() now returns 4.
2. Line 9 renders the same lanes again with renderRootSync: no slices, so no gap where the store could change. That's the second render PriceList.
3. Line 14 goes round again, and this time the tree is committed.

Press Edit & run and change line 12 to const price = getPrice();. Click Show prices: one render, and the page shows Tea 1: $3 next to five rows at $4. React had no note to check, so it committed the torn render.

Concurrent doesn't mean parallel

"Concurrent" can sound like threads: two pieces of work running at the same moment on two processor cores. React doesn't do that. Everything in this lesson ran on the browser's one main thread, taking turns: a slice of React, a turn for the browser, another slice. And React can only take a turn between two fibers, because shouldYield is checked before each unit of work. A component's function is plain JavaScript; nothing can stop it halfway. Compare the same 150 ms of work in one component and in sixty:

1import { memo, startTransition, useLayoutEffect, useState } from "react";2 3function busy(ms) {4  const end = performance.now() + ms;5  while (performance.now() < end) {}6}7 8const BigChart = memo(function BigChart() {9  busy(150); // one slow component: 150 ms10  return <p>One big sales chart</p>;11});12 13function Bar() {14  busy(2.5); // one small component: 2.5 ms15  return <i>|</i>;16}17 18const SmallBars = memo(function SmallBars() {19  return <p>{Array.from({ length: 60 }, (_, n) => <Bar key={n} />)}</p>;20});21 22// Counts the browser's turns while React renders, and the longest wait.23let turns = 0;24let longest = 0;25let watching = false;26function watchTurns() {27  turns = 0;28  longest = 0;29  watching = true;30  let last = performance.now();31  const turn = () => {32    if (!watching) return;33    const now = performance.now();34    longest = Math.max(longest, now - last);35    last = now;36    turns += 1;37    setTimeout(turn);38  };39  setTimeout(turn);40}41 42export default function App() {43  const [chart, setChart] = useState(null);44  const [report, setReport] = useState("Pick a chart.");45 46  useLayoutEffect(() => {47    if (!watching) return;48    watching = false;49    setReport(`Turns the browser got: ${turns}. Longest wait: ${Math.round(longest)} ms.`);50  }, [chart]);51 52  function draw(next) {53    setReport("Drawing...");54    watchTurns();55    startTransition(() => setChart(next));56  }57 58  return (59    <>60      <button onClick={() => draw("big")}>One big chart</button>61      <button onClick={() => draw("small")}>Sixty small bars</button>62      <p>{report}</p>63      {chart === "big" && <BigChart />}64      {chart === "small" && <SmallBars />}65    </>66  );67}

Both charts render in a transition (line 55). Lines 26 to 40 start a timer that counts the browser's turns and the longest wait between two of them, and line 49 reports both after the commit. One big chart reports one or two turns and a wait of about 300 ms (150 ms, twice in StrictMode): the browser was frozen for the whole of BigChart. Sixty small bars reports about sixty turns and short waits. Same work, same transition; the only difference is how many places React may stop. To make a slow screen responsive, split the slow part into smaller components, or do less work.

The commit can't be split either: commitRoot changes the page in one go. So a transition keeps typing smooth only when its render is made of many small fibers and its commit is quick.

Finding thrown-away renders in the Performance panel

In a real app you can't add a log to every row. React's development build already reports its renders to the browser's Performance panel, in a group of tracks named Scheduler. It does that with console.timeStamp, which Chrome draws on the timeline. This version of the overview's shop imports a tracks.js tab first (line 2), which wraps console.timeStamp and copies React's entries into the log. Press Refresh the list.

1import { memo, startTransition, useLayoutEffect, useRef, useState } from "react";2import "./tracks.js";3import { clearLog, note, whenRowsStart } from "./log.js";4 5function busy(ms) {6  const end = performance.now() + ms;7  while (performance.now() < end) {}8}9 10function TeaRow({ n }) {11  busy(2); // a slow row: 2 ms of work12  note(`row ${n}`);13  return <li>Tea {n + 1}</li>;14}15 16const TeaList = memo(function TeaList({ list }) {17  note(`render TeaList, list ${list}`);18  useLayoutEffect(() => note(`commit TeaList, list ${list}`), [list]);19  const rows = Array.from({ length: 40 }, (_, n) => <TeaRow key={n} n={n} />);20  return <ol>{rows}</ol>;21});22 23export default function App() {24  const [list, setList] = useState(1);25  const [cart, setCart] = useState(0);26  const addButton = useRef(null);27  note(`render App: list ${list}, cart ${cart}`);28 29  function refresh() {30    clearLog();31    startTransition(() => setList(list + 1));32    // A shopper clicks Add to cart while the new list renders.33    whenRowsStart(() => addButton.current.click());34  }35 36  return (37    <>38      <button onClick={refresh}>Refresh the list</button>39      <button ref={addButton} onClick={() => setCart(cart + 1)}>40        Add to cart ({cart})41      </button>42      <TeaList list={list} />43    </>44  );45}

In tracks.js, line 4 keeps the real console.timeStamp, and line 9 still calls it, so the Performance panel gets the entries too. Lines 6 and 7 log the Scheduler entries with their track. Right after row 0, the log shows Transition track: Interrupted Render: React noted the dropped draft when prepareFreshStack started the click's render. Then Blocking track: Render and Blocking track: Commit for the click, and Transition track: Render and Transition track: Commit for the second attempt. There are a few more, such as Event: click for the click that started each update.

To see the same thing on the timeline, open the browser's developer tools, start a recording in the Performance panel, press Refresh the list, and stop. The Scheduler group has a Blocking track and a Transition track, and the transition's first attempt is a short bar labeled Interrupted Render. Many of those bars in your own app mean work is being thrown away: often fine, but a sign to check whether something keeps interrupting a slow transition. React's production build leaves these tracks out.

Common mix-ups

• "Concurrent rendering uses several threads." No. React takes turns with the browser on the one main thread.
• "React can pause in the middle of a component." No. It checks shouldYield between fibers. A slow component freezes the page until it returns.
• "An interrupted render picks up where it stopped." No. A pause keeps the draft; an interruption throws it away, and the next attempt starts at the root.
• "Any update interrupts a transition." No. Only a more urgent lane does. Timers, fetch results and other transitions wait for it to finish.
• "A suspending component throws its promise." No. use throws SuspenseException and keeps the promise aside for the work loop.
• "A transition never shows a fallback." No. A boundary that is new, or already showing a fallback, can show its fallback in a transition.
• "Concurrent rendering makes rendering faster." No. The same components run, and thrown-away drafts add work. What it buys is a page that answers clicks and keys while it renders.

Practice exercises

import { memo, startTransition, useLayoutEffect, useRef, useState } from "react";
import { clearLog, note, whenRowsStart } from "./log.js";

function busy(ms) {
  const end = performance.now() + ms;
  while (performance.now() < end) {}
}

function TeaRow({ n }) {
  busy(2); // a slow row: 2 ms of work
  note(`row ${n}`);
  return <li>Tea {n + 1}</li>;
}

const TeaList = memo(function TeaList({ list }) {
  note(`render TeaList, list ${list}`);
  useLayoutEffect(() => note(`commit TeaList, list ${list}`), [list]);
  const rows = Array.from({ length: 40 }, (_, n) => <TeaRow key={n} n={n} />);
  return <ol>{rows}</ol>;
});

export default function App() {
  const [list, setList] = useState(1);
  const [cart, setCart] = useState(0);
  const addButton = useRef(null);
  note(`render App: list ${list}, cart ${cart}`);

  function refresh() {
    clearLog();
    startTransition(() => setList(list + 1));
    // This time the update comes from a timer, not a click.
    whenRowsStart(() => setCart((n) => n + 1));
  }

  return (
    <>
      <button onClick={refresh}>Refresh the list</button>
      <button ref={addButton} onClick={() => setCart(cart + 1)}>
        Add to cart ({cart})
      </button>
      <TeaList list={list} />
    </>
  );
}

import { memo, startTransition, useLayoutEffect, useRef, useState } from "react";
import { clearLog, note, whenRowsStart } from "./log.js";

function busy(ms) {
  const end = performance.now() + ms;
  while (performance.now() < end) {}
}

function TeaRow({ n }) {
  busy(2); // a slow row: 2 ms of work
  note(`row ${n}`);
  return <li>Tea {n + 1}</li>;
}

const TeaList = memo(function TeaList({ list }) {
  note(`render TeaList, list ${list}`);
  useLayoutEffect(() => note(`commit TeaList, list ${list}`), [list]);
  const rows = Array.from({ length: 40 }, (_, n) => <TeaRow key={n} n={n} />);
  return <ol>{rows}</ol>;
});

export default function App() {
  const [list, setList] = useState(1);
  const [cart, setCart] = useState(0);
  const addButton = useRef(null);
  note(`render App: list ${list}, cart ${cart}`);

  function refresh() {
    clearLog();
    startTransition(() => setList(list + 1));
    // This time the update comes from a timer, not a click.
    whenRowsStart(() => setCart((n) => n + 1));
  }

  return (
    <>
      <button onClick={refresh}>Refresh the list</button>
      <button ref={addButton} onClick={() => setCart(cart + 1)}>
        Add to cart ({cart})
      </button>
      <TeaList list={list} />
    </>
  );
}

import { Suspense, use } from "react";

const reviewsPromise = new Promise((resolve) => {
  setTimeout(() => resolve(["Lovely", "Fast delivery"]), 500);
});

function Reviews() {
  const reviews = use(reviewsPromise);
  return (
    <>
      <p>{reviews.length} reviews</p>
      <p>status: {reviewsPromise.status}</p>
    </>
  );
}

export default function App() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <Reviews />
    </Suspense>
  );
}

import { Suspense, use } from "react";

const reviewsPromise = new Promise((resolve) => {
  setTimeout(() => resolve(["Lovely", "Fast delivery"]), 500);
});

function Reviews() {
  const reviews = use(reviewsPromise);
  return (
    <>
      <p>{reviews.length} reviews</p>
      <p>status: {reviewsPromise.status}</p>
    </>
  );
}

export default function App() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <Reviews />
    </Suspense>
  );
}

1import { Suspense, use, useLayoutEffect, useState } from "react";2import { clearLog, note } from "./log.js";3import { fetchReviews } from "./api.js";4 5function Reviews({ product }) {6  const promise = fetchReviews(product);7  note(`render Reviews ${product}: status ${promise.status ?? "not set"}`);8  const reviews = use(promise);9  useLayoutEffect(() => note(`commit Reviews ${product}`), [product]);10  return <ul>{reviews.map((review) => <li key={review}>{review}</li>)}</ul>;11}12 13function Loading() {14  useLayoutEffect(() => note("commit Loading"), []);15  return <p>Loading reviews...</p>;16}17 18const products = ["Green tea", "Black tea", "Mint tea"];19 20export default function App() {21  const [product, setProduct] = useState("Green tea");22  note(`render App: ${product}`);23 24  function show(next) {25    clearLog();26    setProduct(next);27  }28 29  return (30    <>31      {products.map((name) => (32        <button key={name} onClick={() => show(name)} aria-pressed={name === product}>33          {name}34        </button>35      ))}36      <Suspense fallback={<Loading />}>37        <Reviews product={product} />38      </Suspense>39    </>40  );41}

1import { Suspense, startTransition, use, useLayoutEffect, useState } from "react";2import { clearLog, note } from "./log.js";3import { fetchReviews } from "./api.js";4 5function Reviews({ product }) {6  const promise = fetchReviews(product);7  note(`render Reviews ${product}: status ${promise.status ?? "not set"}`);8  const reviews = use(promise);9  useLayoutEffect(() => note(`commit Reviews ${product}`), [product]);10  return <ul>{reviews.map((review) => <li key={review}>{review}</li>)}</ul>;11}12 13function Loading() {14  useLayoutEffect(() => note("commit Loading"), []);15  return <p>Loading reviews...</p>;16}17 18const products = ["Green tea", "Black tea", "Mint tea"];19 20export default function App() {21  const [product, setProduct] = useState("Green tea");22  note(`render App: ${product}`);23 24  function show(next) {25    clearLog();26    startTransition(() => setProduct(next));27  }28 29  return (30    <>31      {products.map((name) => (32        <button key={name} onClick={() => show(name)} aria-pressed={name === product}>33          {name}34        </button>35      ))}36      <Suspense fallback={<Loading />}>37        <Reviews product={product} />38      </Suspense>39    </>40  );41}

const SyncLane = 0b10; // 2: a click or a key
const InputContinuousLane = 0b1000; // 8: a mouse move
const DefaultLane = 0b100000; // 32: a timer
const TransitionLane1 = 0b100000000; // 256: the first transition lane
const TransitionLane2 = 0b1000000000; // 512: the next one
const TransitionLanes = 0b0000000001111111111111100000000;

// TODO: return true when an update in nextLane should throw away
// a render that is working on wipLane, as getNextLanes decides.
function interrupts(wipLane, nextLane) {
}

for (const lane of [SyncLane, InputContinuousLane, DefaultLane, TransitionLane2]) {
  console.log(interrupts(TransitionLane1, lane));
}

const SyncLane = 0b10; // 2: a click or a key
const InputContinuousLane = 0b1000; // 8: a mouse move
const DefaultLane = 0b100000; // 32: a timer
const TransitionLane1 = 0b100000000; // 256: the first transition lane
const TransitionLane2 = 0b1000000000; // 512: the next one
const TransitionLanes = 0b0000000001111111111111100000000;

function interrupts(wipLane, nextLane) {
  const keepWorking =
    nextLane >= wipLane ||
    (nextLane === DefaultLane && (wipLane & TransitionLanes) !== 0);
  return !keepWorking;
}

for (const lane of [SyncLane, InputContinuousLane, DefaultLane, TransitionLane2]) {
  console.log(interrupts(TransitionLane1, lane));
}

1import { startTransition, useLayoutEffect, useState, useSyncExternalStore } from "react";2import { clearLog, note, whenRowsStart } from "./log.js";3import { getPrice, raisePrice, subscribe } from "./store.js";4 5function busy(ms) {6  const end = performance.now() + ms;7  while (performance.now() < end) {}8}9 10function PriceRow({ n }) {11  busy(4); // a slow row12  const price = getPrice();13  note(`row ${n} reads $${price}`);14  return <li>Tea {n + 1}: ${price}</li>;15}16 17function PriceList() {18  note("render PriceList");19  useLayoutEffect(() => note("commit PriceList"), []);20  return <ol>{[0, 1, 2, 3, 4, 5].map((n) => <PriceRow key={n} n={n} />)}</ol>;21}22 23export default function App() {24  const [shown, setShown] = useState(false);25 26  function showPrices() {27    clearLog();28    startTransition(() => setShown(true));29    // The price changes while the rows render.30    whenRowsStart(raisePrice);31  }32 33  return (34    <>35      <button onClick={showPrices} disabled={shown}>Show prices</button>36      {shown && <PriceList />}37    </>38  );39}

1import { startTransition, useLayoutEffect, useState, useSyncExternalStore } from "react";2import { clearLog, note, whenRowsStart } from "./log.js";3import { getPrice, raisePrice, subscribe } from "./store.js";4 5function busy(ms) {6  const end = performance.now() + ms;7  while (performance.now() < end) {}8}9 10function PriceRow({ n }) {11  busy(4); // a slow row12  const price = useSyncExternalStore(subscribe, getPrice);13  note(`row ${n} reads $${price}`);14  return <li>Tea {n + 1}: ${price}</li>;15}16 17function PriceList() {18  note("render PriceList");19  useLayoutEffect(() => note("commit PriceList"), []);20  return <ol>{[0, 1, 2, 3, 4, 5].map((n) => <PriceRow key={n} n={n} />)}</ol>;21}22 23export default function App() {24  const [shown, setShown] = useState(false);25 26  function showPrices() {27    clearLog();28    startTransition(() => setShown(true));29    // The price changes while the rows render.30    whenRowsStart(raisePrice);31  }32 33  return (34    <>35      <button onClick={showPrices} disabled={shown}>Show prices</button>36      {shown && <PriceList />}37    </>38  );39}

let workInProgress = null; // the next row to render, or null
let renderLanes = null; // the lanes the draft is for
const log = [];

function prepareFreshStack(lanes) {
  workInProgress = 0;
  renderLanes = lanes;
  log.push(`start ${lanes}`);
}

function performUnitOfWork() {
  log.push(`row ${workInProgress}`);
  workInProgress = workInProgress === 5 ? null : workInProgress + 1;
}

// One slice of work: at most two rows.
function renderSlice(lanes) {
  // TODO: like renderRootConcurrent, start a fresh draft only when
  // there is no draft yet, or the lanes changed.
  prepareFreshStack(lanes);
  let units = 0;
  while (workInProgress !== null && units < 2) {
    performUnitOfWork();
    units += 1;
  }
}

renderSlice("transition");
renderSlice("transition");
console.log(log.join(", "));

let workInProgress = null; // the next row to render, or null
let renderLanes = null; // the lanes the draft is for
const log = [];

function prepareFreshStack(lanes) {
  workInProgress = 0;
  renderLanes = lanes;
  log.push(`start ${lanes}`);
}

function performUnitOfWork() {
  log.push(`row ${workInProgress}`);
  workInProgress = workInProgress === 5 ? null : workInProgress + 1;
}

// One slice of work: at most two rows.
function renderSlice(lanes) {
  if (workInProgress === null || renderLanes !== lanes) {
    prepareFreshStack(lanes);
  }
  let units = 0;
  while (workInProgress !== null && units < 2) {
    performUnitOfWork();
    units += 1;
  }
}

renderSlice("transition");
renderSlice("transition");
console.log(log.join(", "));

Check your understanding

Key takeaways

• A concurrent render is a draft in the work-in-progress tree; the page changes only when a draft is committed.
• Between slices, renderRootConcurrent goes on from workInProgress when the root and lanes are the same, and calls prepareFreshStack when they changed.
• A more urgent lane, such as a click's SyncLane, throws a transition's draft away; DefaultLane and other transitions wait for it.
• use marks the promise and throws SuspenseException. Urgent updates commit the fallback and retry the boundary; a transition in the shell commits nothing until the ping.
• useDeferredValue returns the old value in the urgent render and asks for a second render on a transition lane.
• After a sliced render, React checks every useSyncExternalStore snapshot and renders again with renderRootSync if one changed.
• It all runs on one thread, and React can only stop between fibers.

Coming next: React's event system. It follows the click from this lesson from the browser to your handler, and shows where its SyncLane comes from.