Reconciliation and the diffing algorithm

Move one row, and React moves three

Every time state changes, React calls your components again and gets new elements back. Most of them describe things that are already on the page. Before React can change the page, it has to answer one question for every new element: which thing that already exists is this? That matching is called reconciliation, and this lesson reads the code that does it, ReactChildFiber.js, at React 19.3.1.

You have seen what it does from the outside: Render and commit showed that React changes only what differs, Rendering lists showed why list items need keys, and Preserving and resetting state showed that state belongs to a place in the tree. Start with a grocery list whose rows have keys. Type 2 in the box next to Dates, then press the button.

1import { useState } from "react";2import { useDomReport } from "./watch.js";3 4const groceries = [5  { id: "apple", name: "Apples" },6  { id: "bread", name: "Bread" },7  { id: "cheese", name: "Cheese" },8  { id: "dates", name: "Dates" },9];10 11export default function App() {12  const [items, setItems] = useState(groceries);13  const [listRef, report] = useDomReport();14 15  function moveLastToTop() {16    setItems([items.at(-1), ...items.slice(0, -1)]);17  }18 19  return (20    <>21      <button onClick={moveLastToTop}>Move the last row to the top</button>22      <ul ref={listRef}>23        {items.map((item) => (24          <li key={item.id}>25            <label>26              {item.name} <input size={3} />27            </label>28          </li>29        ))}30      </ul>31      <p>What React changed in the list:</p>32      <ol className="report">33        {report.map((line) => (34          <li key={line}>{line}</li>35        ))}36      </ol>37    </>38  );39}

Lines 4 to 9 are the groceries, each with an id. Line 12 keeps them in state. Line 13 calls useDomReport, a small hook in the watch.js tab: it watches the list with a MutationObserver, the browser's tool for recording changes to the page, and returns a ref for the list and the report of what changed in the last commit. You don't need to read watch.js; it comes back in later examples. Lines 15 to 17 build a new array with the last item first, using at(-1) and slice. Line 24 keys each row by its id, and line 26 gives each row a box to type in. Lines 32 to 36 show the report.

After the click, Dates sits at the top with your 2 still in its box: React kept that row's <li>, box and all. But read the report: moved <li> Apples, moved <li> Bread, moved <li> Cheese. You moved one row. React moved the other three, and Dates never moved at all. The page ends up the same either way, but it isn't what most people expect, and by the end of this lesson you'll be able to predict it.

Where reconciliation runs

A fiber is React's record for one component or DOM element in the tree: its type, its key, its props, its DOM node (stateNode), and links to its first child, its next sibling and its parent, return. React keeps two trees of them: current, what's on the screen, and the work-in-progress tree it builds during a render. Each fiber's alternate points at its copy in the other tree. The Fiber lesson covers these fields; here you only need the idea.

During a render, the work loop visits fibers one at a time and calls beginWork on each. For a function component, beginWork calls your function, then hands what it returned to reconciliation. This is the end of updateFunctionComponent, in ReactFiberBeginWork.js:

  if (current !== null && !didReceiveUpdate) {
    bailoutHooks(current, workInProgress, renderLanes);
    return bailoutOnAlreadyFinishedWork(current, workInProgress, renderLanes);
  }

  if (getIsHydrating() && hasId) {
    pushMaterializedTreeId(workInProgress);
  }

  // React DevTools reads this flag.
  workInProgress.flags |= PerformedWork;
  reconcileChildren(current, workInProgress, nextChildren, renderLanes);
  return workInProgress.child;

In plain words, line by line:

1. Lines 1 to 4 skip the children when nothing changed: a bailout. The last big section of this lesson comes back to it.
2. Lines 6 to 8 only matter during hydration, when React takes over HTML from the server.
3. Line 11 marks the fiber as having rendered. The comment says why: React DevTools reads the flag.
4. Line 12 is reconciliation. nextChildren is what your component returned, and reconcileChildren compares it with this fiber's children.
5. Line 13 returns the first child. The work loop visits it next, and reconciles its children in turn.

So reconciliation happens one level at a time, as the work loop goes down the tree: a component's children are compared only when React gets to that component. Here is reconcileChildren, from lines 339 to 370 with its comments left out. The source is written in Flow, a type checker like TypeScript: the text after each colon, like : Fiber | null, is a type, and you can read past it.

export function reconcileChildren(
  current: Fiber | null,
  workInProgress: Fiber,
  nextChildren: any,
  renderLanes: Lanes,
) {
  if (current === null) {
    workInProgress.child = mountChildFibers(
      workInProgress,
      null,
      nextChildren,
      renderLanes,
    );
  } else {
    workInProgress.child = reconcileChildFibers(
      workInProgress,
      current.child,
      nextChildren,
      renderLanes,
    );
  }
}

1. Line 7 asks whether this fiber has a current twin. If not, the component is appearing for the first time, and lines 8 to 13 use mountChildFibers.
2. Otherwise lines 15 to 20 use reconcileChildFibers, with current.child, the first old child, and nextChildren, the new elements. Either way, the result becomes workInProgress.child.

The two functions are the same code. The end of ReactChildFiber.js builds both from one factory:

export const reconcileChildFibers: ChildReconciler =
  createChildReconciler(true);
export const mountChildFibers: ChildReconciler = createChildReconciler(false);

createChildReconciler takes one setting, shouldTrackSideEffects. With true, the functions inside it record what the commit must do: which children to insert, move and delete. With false, they skip that. A component that is mounting has nothing old to compare with, and its whole subtree will be inserted in one go from its top, so marking each child would be wasted work.

Inside, one function looks at what the component returned and hands it to the right helper. How to read the table: each row is something a component can return, the function in reconcileChildFibersImpl that compares it with the old children, and what that function does.

Same type and key: keep the fiber, change the props

Most of the time a component returns one element where it returned one before. This card can be highlighted, and it can switch its outer tag. Type a note in the box, then press Highlight the card.

1import { useState } from "react";2import { useDomReport } from "./watch.js";3 4export default function App() {5  const [highlight, setHighlight] = useState(false);6  const [asSection, setAsSection] = useState(false);7  const [cardRef, report] = useDomReport();8  const className = highlight ? "card highlight" : "card";9 10  return (11    <>12      <button onClick={() => setHighlight(!highlight)}>Highlight the card</button>13      <button onClick={() => setAsSection(!asSection)}>Switch div and section</button>14      <div ref={cardRef}>15        {asSection ? (16          <section className={className}>17            <h3>Delivery notes</h3>18            <textarea rows={2} />19          </section>20        ) : (21          <div className={className}>22            <h3>Delivery notes</h3>23            <textarea rows={2} />24          </div>25        )}26      </div>27      <ol className="report">28        {report.map((line) => (29          <li key={line}>{line}</li>30        ))}31      </ol>32    </>33  );34}

Lines 5 and 6 keep two switches in state, and line 8 picks the class name. Line 12 flips highlight, and line 13 flips asSection. Lines 15 to 25 return a <section> or a <div> with the same heading and box inside. Line 14 is the element watch.js watches.

After Highlight the card, the report says changed the class attribute, and your note is still in the box. React kept the <div>, the heading and the box, and changed one attribute. Here is the code that made that choice. A single element goes to reconcileSingleElement; this version is simplified, with the Fragment branch, the development-only lines and a few special cases (hot reloading, lazy components, and an experimental kind of key) left out.

  function reconcileSingleElement(
    returnFiber: Fiber,
    currentFirstChild: Fiber | null,
    element: ReactElement,
    lanes: Lanes,
  ): Fiber {
    const key = element.key;
    let child = currentFirstChild;
    while (child !== null) {
      if (child.key === key) {
        const elementType = element.type;
        if (child.elementType === elementType) {
          deleteRemainingChildren(returnFiber, child.sibling);
          const existing = useFiber(child, element.props);
          coerceRef(existing, element);
          existing.return = returnFiber;
          return existing;
        }
        // Didn't match.
        deleteRemainingChildren(returnFiber, child);
        break;
      } else {
        deleteChild(returnFiber, child);
      }
      child = child.sibling;
    }

    const created = createFiberFromElement(element, returnFiber.mode, lanes);
    coerceRef(created, element);
    created.return = returnFiber;
    return created;
  }

1. Line 7 reads the new element's key. Here there is none, so it's null, and an old child with no key matches it.
2. Lines 9 and 25 walk the old children, from the first one through each sibling. Usually there is only one.
3. Line 10 compares keys. When they match, line 12 compares types: elementType is "div" for a <div>, or the function itself for a component like NoteBox.
4. Same key and same type: line 13 deletes any other old children after this one, line 14 reuses the old fiber with the new props, line 15 attaches the new ref, and line 17 returns it.
5. Lines 19 to 21: the key matched but the type didn't. React deletes this child and every one after it, and stops looking.
6. Line 23: a different key. This old child isn't the one, so it's deleted, and the loop tries the next.
7. Lines 28 to 31: nothing matched, so createFiberFromElement makes a brand-new fiber from the element's type, key and props.

The reuse happens in useFiber. Despite its name, it isn't a hook, and you never call it:

  function useFiber(fiber: Fiber, pendingProps: mixed): Fiber {
    // We currently set sibling to null and index to 0 here because it is easy
    // to forget to do before returning it. E.g. for the single child case.
    const clone = createWorkInProgress(fiber, pendingProps);
    clone.index = 0;
    clone.sibling = null;
    return clone;
  }

Line 4 calls createWorkInProgress, which takes the old fiber's alternate (or makes one) and gives it the new props as pendingProps. The copy keeps the old fiber's stateNode, so the <div> on the page and the box inside it stay the same DOM nodes. Lines 5 and 6 reset its position and sibling, because the caller sets them again. Later in the render, React notices the new props and marks the fiber with an Update flag; the commit phase then changes the class attribute.

A different type replaces the whole subtree

Now type a new note in the card above and press Switch div and section. The report says removed <div> Delivery notes, then added <section> Delivery notes, and your note is gone. The heading and the box are exactly the same in both branches, but React made new ones anyway.

In reconcileSingleElement, both elements have the key null, so line 10 matches, but line 12 compares "div" with "section". Lines 19 to 21 delete the old child, and lines 28 to 31 create a new fiber. Nothing inside the old <div> is ever compared: the new <section>'s children start with no old fibers at all. Deleting a fiber doesn't touch the page yet. It goes on a list, in deleteChild:

  function deleteChild(returnFiber: Fiber, childToDelete: Fiber): void {
    if (!shouldTrackSideEffects) {
      // Noop.
      return;
    }
    const deletions = returnFiber.deletions;
    if (deletions === null) {
      returnFiber.deletions = [childToDelete];
      returnFiber.flags |= ChildDeletion;
    } else {
      deletions.push(childToDelete);
    }
  }

1. Lines 2 to 5: a mounting subtree has nothing to delete, so this does nothing.
2. Lines 6 to 9: the parent fiber keeps a deletions array. The first deletion creates it and sets the parent's ChildDeletion flag, so the commit knows to look.
3. Line 11: later deletions are added to the same array.

The commit phase removes the old DOM nodes before it inserts new ones, which is why the report lists the removal first. The commit phase lesson follows this list from there.

Why throw away a subtree that looks the same? Because finding the smallest set of changes between two trees is a hard problem. The best general methods take on the order of n³ steps for n elements: a billion steps for a thousand elements. React gives that up for a pass that grows with the number of elements, and makes two assumptions to stay correct for real apps:

• Two elements of different types produce different trees, so React doesn't look inside a replaced one.
• Keys tell React which children are the same between renders, so it doesn't have to guess from their order or content.

The first assumption is behind a rule from Preserving and resetting state: never define a component inside another component. Each render would make a new function, a new type, and a new subtree with empty state. How to read the table: each row is a change at one place in the tree, what reconcileSingleElement does with it, and what survives.

Lists: walk while the keys match, then use a map

When a component returns an array, like the result of items.map(…), React compares it with reconcileChildrenArray. The old children are a chain: the first child, then each one's sibling, so React walks them from left to right. This version is simplified: the development-only checks, the hydration lines and a branch for empty slots (like null children) are left out, and // … marks two places where the code links the new fiber into the list, as lines 29 to 34 do.

function reconcileChildrenArray(
  returnFiber: Fiber,
  currentFirstChild: Fiber | null,
  newChildren: Array<any>,
  lanes: Lanes,
): Fiber | null {
  let resultingFirstChild: Fiber | null = null;
  let previousNewFiber: Fiber | null = null;

  let oldFiber = currentFirstChild;
  let lastPlacedIndex = 0;
  let newIdx = 0;
  let nextOldFiber = null;
  for (; oldFiber !== null && newIdx < newChildren.length; newIdx++) {
    nextOldFiber = oldFiber.sibling;
    const newFiber = updateSlot(
      returnFiber,
      oldFiber,
      newChildren[newIdx],
      lanes,
    );
    if (newFiber === null) {
      break;
    }
    if (oldFiber && newFiber.alternate === null) {
      deleteChild(returnFiber, oldFiber);
    }
    lastPlacedIndex = placeChild(newFiber, lastPlacedIndex, newIdx);
    if (previousNewFiber === null) {
      resultingFirstChild = newFiber;
    } else {
      previousNewFiber.sibling = newFiber;
    }
    previousNewFiber = newFiber;
    oldFiber = nextOldFiber;
  }

  if (newIdx === newChildren.length) {
    deleteRemainingChildren(returnFiber, oldFiber);
    return resultingFirstChild;
  }

  if (oldFiber === null) {
    for (; newIdx < newChildren.length; newIdx++) {
      const newFiber = createChild(returnFiber, newChildren[newIdx], lanes);
      lastPlacedIndex = placeChild(newFiber, lastPlacedIndex, newIdx);
      // …
    }
    return resultingFirstChild;
  }

  const existingChildren = mapRemainingChildren(oldFiber);

  for (; newIdx < newChildren.length; newIdx++) {
    const newFiber = updateFromMap(
      existingChildren,
      returnFiber,
      newIdx,
      newChildren[newIdx],
      lanes,
    );
    if (newFiber !== null) {
      const currentFiber = newFiber.alternate;
      if (currentFiber !== null) {
        existingChildren.delete(
          currentFiber.key === null ? newIdx : currentFiber.key,
        );
      }
      lastPlacedIndex = placeChild(newFiber, lastPlacedIndex, newIdx);
      // …
    }
  }

  existingChildren.forEach(child => deleteChild(returnFiber, child));
  return resultingFirstChild;
}

In plain words, part by part:

1. Lines 10 to 13 set up: oldFiber is the first old child, newIdx counts through the new elements, and lastPlacedIndex starts at 0.
2. Lines 14 to 36 are the first pass. At each position, updateSlot (line 16) compares the old fiber there with the new element. Same key: it returns a fiber, reused when the type matches too. Different key: it returns null, and line 23 stops the pass. Lines 25 to 27 delete the old fiber when the key matched but a new fiber had to be made. Line 28 calls placeChild, and lines 29 to 34 chain the new fiber after the previous one.
3. Lines 38 to 41: if every new element found a match, the new list is done, and anything left in the old list is deleted. Removing rows from the end costs nothing else.
4. Lines 43 to 50: if the old list ran out first, every remaining new element is created and inserted. Adding to the end is cheap too.
5. Line 52: otherwise, the rest of the old children go into a Map, keyed by their key, or by their position when they have none.
6. Lines 54 to 72 are the second pass. For each remaining new element, updateFromMap (line 55) looks up its key. A fiber found there is reused, and lines 64 to 68 take it out of the map. Then line 69 calls placeChild.
7. Line 74: every old child still in the map was never claimed, so it's deleted.

Whether a reused child moves is decided in placeChild, shown here as it is:

  function placeChild(
    newFiber: Fiber,
    lastPlacedIndex: number,
    newIndex: number,
  ): number {
    newFiber.index = newIndex;
    if (!shouldTrackSideEffects) {
      // During hydration, the useId algorithm needs to know which fibers are
      // part of a list of children (arrays, iterators).
      newFiber.flags |= Forked;
      return lastPlacedIndex;
    }
    const current = newFiber.alternate;
    if (current !== null) {
      const oldIndex = current.index;
      if (oldIndex < lastPlacedIndex) {
        // This is a move. The fiber already existed, so this is not a new
        // mount; don't set PlacementDEV, which would cause StrictMode to
        // re-run the effects in its subtree as if it had remounted.
        newFiber.flags |= Placement;
        return lastPlacedIndex;
      } else {
        // This item can stay in place.
        return oldIndex;
      }
    } else {
      // This is an insertion.
      newFiber.flags |= Placement | PlacementDEV;
      return lastPlacedIndex;
    }
  }

1. Line 6 saves the child's new position.
2. Lines 7 to 12: a mounting subtree records no moves. (The Forked flag helps useId during hydration.)
3. Lines 13 to 15: a reused child has an alternate, the old fiber, and oldIndex is where it was.
4. Lines 16 to 21: if it was before lastPlacedIndex, it must move. It gets the Placement flag, and lastPlacedIndex stays the same.
5. Lines 22 to 25: otherwise it can stay where it is, and its old index becomes the new lastPlacedIndex.
6. Lines 26 to 30: a new child is an insertion: Placement, plus PlacementDEV, which tells StrictMode to run its Effects twice as a new mount.

In plain words, lastPlacedIndex is the furthest-right old position that React has decided to leave alone so far. React reads the new list from left to right. A reused child whose old position is to the left of that point used to come before a child that now comes before it, so it has to move. Anything to the right can stay, and pushes the point further right.

The map comes from mapRemainingChildren, simplified here (the real declaration on line 7 has a long type, and one experimental branch is left out):

  function mapRemainingChildren(
    currentFirstChild: Fiber,
  ): Map<string | number | ReactOptimisticKey, Fiber> {
    // Add the remaining children to a temporary map so that we can find them by
    // keys quickly. Implicit (null) keys get added to this set with their index
    // instead.
    const existingChildren = new Map();

    let existingChild: null | Fiber = currentFirstChild;
    while (existingChild !== null) {
      if (existingChild.key === null) {
        existingChildren.set(existingChild.index, existingChild);
      } else {
        existingChildren.set(existingChild.key, existingChild);
      }
      existingChild = existingChild.sibling;
    }
    return existingChildren;
  }

Lines 10 to 17 walk the old children that are left. Line 12 stores a child with no key under its position, and line 14 stores a keyed child under its key. That's why position keys and no keys behave alike: both pair children up by position.

Now step through it yourself. Pick a change to the grocery list, then press Next step. Each step marks the line of reconcileChildrenArray it's about and shows the old fibers, the new elements, lastPlacedIndex and the map.

8  let previousNewFiber: Fiber | null = null;9 10  let oldFiber = currentFirstChild;11  let lastPlacedIndex = 0;12  let newIdx = 0;13  let nextOldFiber = null;14  for (; oldFiber !== null && newIdx < newChildren.length; newIdx++) {

Compare the changes. Move Apples to the bottom costs one move: Bread, Cheese and Dates each keep pushing lastPlacedIndex to the right, and only Apples is left behind. Move Dates to the top costs three: Dates sets lastPlacedIndex to 3 straight away, and everything after it is to its left. Add Eggs at the top costs one insertion and no moves, and Remove Bread costs one deletion.

Counting real DOM moves, with and without keys

The step-through replays a model of the code. This list runs the real React 19.3.1, and watch.js reports every DOM change it makes. Try each button, and compare the report with the step-through.

1import { useState } from "react";2import { useDomReport } from "./watch.js";3 4const groceries = [5  { id: "apple", name: "Apples" },6  { id: "bread", name: "Bread" },7  { id: "cheese", name: "Cheese" },8  { id: "dates", name: "Dates" },9];10 11export default function App() {12  const [items, setItems] = useState(groceries);13  const [byPosition, setByPosition] = useState(false);14  const [listRef, report] = useDomReport();15 16  return (17    <>18      <button onClick={() => setItems([items.at(-1), ...items.slice(0, -1)])}>Last to top</button>19      <button onClick={() => setItems([...items.slice(1), items[0]])}>First to bottom</button>20      <button onClick={() => setItems(items.toReversed())}>Reverse</button>21      <label>22        <input type="checkbox" checked={byPosition} onChange={(event) => setByPosition(event.target.checked)} />23        Key by position24      </label>25      <ul ref={listRef}>26        {items.map((item, index) => (27          <li key={byPosition ? index : item.id}>28            <label>29              {item.name} <input size={3} />30            </label>31          </li>32        ))}33      </ul>34      <ol className="report">35        {report.map((line) => (36          <li key={line}>{line}</li>37        ))}38      </ol>39    </>40  );41}

Lines 18 to 20 are three ways to reorder the same four rows: last to top, first to bottom, and toReversed(), which returns a reversed copy. Lines 21 to 24 are a checkbox that switches line 27 from the id to the position, index, as the key.

With ids as keys, Last to top reports three moved rows, First to bottom reports one, and Reverse reports three: exactly what placeChild predicted. The moves the commit makes are the Placement flags, nothing more. Why can't React notice that one move would do? The comment at the top of reconcileChildrenArray answers it:

    // This algorithm can't optimize by searching from both ends since we
    // don't have backpointers on fibers. I'm trying to see how far we can get
    // with that model. If it ends up not being worth the tradeoffs, we can
    // add it later.

A fiber knows its next sibling but not the one before it, so React can only walk the old children forward. Some other libraries also search from the end, which makes moving the last row to the top cheap. React chose the simpler forward walk: most list changes add or remove rows, or move a few, and a move of a DOM node is fast.

Now tick Key by position. The report lists four removed rows and four added rows: every key changed from an id to a number, so no old fiber matches, and every row is made again. Type a number next to Apples and press Last to top. The report shows four changed text to … lines and no moves, and your number stays in the first row, now next to another name. Keys 0, 1, 2 and 3 all match in the first pass, so React reuses each row where it is and only changes its text. The boxes, and anything else a row holds, stay where they were.

Bailouts: when React skips a component

Reconciliation only runs for the components React calls. The work loop lesson read the check at the start of beginWork: when a fiber gets the same props object as last time and has no update or context change of its own, React skips it without calling it. That's a bailout. Read the console, then press Switch theme.

1import { useState } from "react";2 3function ProductList({ from }) {4  console.log(`ProductList ${from} renders`);5  return (6    <ul>7      <li>Apples</li>8      <li>Bread</li>9    </ul>10  );11}12 13function Layout({ children }) {14  const [dark, setDark] = useState(false);15  console.log("Layout renders");16  return (17    <div className={dark ? "page dark" : "page"}>18      <button onClick={() => setDark(!dark)}>Switch theme</button>19      {children}20      <ProductList from="made by Layout" />21    </div>22  );23}24 25export default function App() {26  return (27    <Layout>28      <ProductList from="made by App" />29    </Layout>30  );31}

ProductList (lines 3 to 11) logs every time React calls it. Layout (lines 13 to 23) holds a theme in state, shows the children it was given on line 19, and makes a second list itself on line 20. App (lines 25 to 31) passes the first list in as children. On the first render, the console shows Layout renders, ProductList made by App renders and ProductList made by Layout renders, each with a small 2 beside it, because StrictMode calls components twice in development.

Press Switch theme. The console adds Layout renders and ProductList made by Layout renders, and nothing for the list made by App. Both lists have the same props, so why does only one render? The list made by App was created during App's render, as the element <ProductList from="made by App" />. App didn't render again, so Layout's children is the very same element object, with the very same props object, and the props check in beginWork compares props objects with !==, not their contents. The other list is a new element made by Layout's new render, with a new props object, so it renders, even though from is the same text. memo changes this by comparing the props one by one.

For reconciliation, a bailout means the fiber's children are never compared. If nothing below the fiber has work, the whole subtree is skipped. If something does, React copies the children as they are and goes on down, in cloneChildFibers, the last function in ReactChildFiber.js:

export function cloneChildFibers(
  current: Fiber | null,
  workInProgress: Fiber,
): void {
  if (current !== null && workInProgress.child !== current.child) {
    throw new Error('Resuming work not yet implemented.');
  }

  if (workInProgress.child === null) {
    return;
  }

  let currentChild = workInProgress.child;
  let newChild = createWorkInProgress(currentChild, currentChild.pendingProps);
  workInProgress.child = newChild;

  newChild.return = workInProgress;
  while (currentChild.sibling !== null) {
    currentChild = currentChild.sibling;
    newChild = newChild.sibling = createWorkInProgress(
      currentChild,
      currentChild.pendingProps,
    );
    newChild.return = workInProgress;
  }
  newChild.sibling = null;
}

1. Lines 5 to 7: a safety check. The children must still be the old ones; the error message says React can't resume half-done work here.
2. Lines 9 to 11: no children, nothing to copy.
3. Lines 13 to 15 copy the first child with createWorkInProgress, the same function useFiber calls. But the props it passes are the child's old pendingProps: the same object as before.
4. Lines 18 to 25 do the same for every sibling, and line 26 ends the list.

Compare it with reconcileChildren: no new elements, no keys, no flags. Each copied child keeps its old props object, so when the work loop reaches it, the same props check passes again, and the bailout carries on down until it reaches the fiber that has the update. That's how one setState deep in a tree renders only the component that owns it.

One more bailout happens after a component runs. Look back at lines 1 to 4 of updateFunctionComponent in the first section: if a component rendered because of a state update but every state value came out the same, didReceiveUpdate is still false, and React skips reconcileChildren, calling bailoutOnAlreadyFinishedWork instead. When does React render again? covers these rules from the outside.

Loading older chat messages without rewriting the list

A support chat shows the newest messages and loads older ones at the top when you scroll up. Adding to the top of a list is where keys earn their keep. Press Load an older message.

1import { useState } from "react";2import { useDomReport } from "./watch.js";3 4const older = [5  { id: 1, text: "Hi, is the blue mug in stock?" },6  { id: 2, text: "Yes, we have three left." },7  { id: 3, text: "Great, can you hold one?" },8];9 10export default function App() {11  const [messages, setMessages] = useState([12    { id: 4, text: "Sure, until Friday." },13    { id: 5, text: "Thank you!" },14  ]);15  const [byPosition, setByPosition] = useState(false);16  const [listRef, report] = useDomReport();17 18  function loadOlder() {19    const next = older.findLast((message) => message.id < messages[0].id);20    if (next) setMessages([next, ...messages]);21  }22 23  return (24    <>25      <button onClick={loadOlder} disabled={messages[0].id === 1}>26        Load an older message27      </button>28      <label>29        <input type="checkbox" checked={byPosition} onChange={(event) => setByPosition(event.target.checked)} />30        Key by position31      </label>32      <ul ref={listRef}>33        {messages.map((message, index) => (34          <li key={byPosition ? index : message.id}>{message.text}</li>35        ))}36      </ul>37      <ol className="report">38        {report.map((line) => (39          <li key={line}>{line}</li>40        ))}41      </ol>42    </>43  );44}

Lines 4 to 8 are the older messages the server would send. Lines 11 to 14 start the chat with the two newest. On line 19, findLast picks the newest older message still to load, and line 20 puts it at the top. Line 34 keys each message by its id, or by its position when the box on lines 28 to 31 is ticked.

With ids, the report says only added <li> Great, can you hold one?. The first pass stops at once, because key 3 isn't key 4. In the second pass, message 3 is new, and messages 4 and 5 keep their old positions, 0 and 1, in order, so nothing moves. Now tick Key by position, which rebuilds every row because every key changes, and load another message. The report lists a changed text to … line for every row that was already there, then an added row at the bottom: each row was reused by position and given another message's text. In a real chat, anything a row holds, like an open menu or a loaded image, would end up next to the wrong message.

Common mix-ups

• "React compares the old and new trees to find the smallest change." No. It makes one pass, level by level, and assumes that a different type means a different subtree and that keys say which children are the same.
• "With keys, React moves only the row I moved." No. It walks forward and moves every reused child whose old position is below lastPlacedIndex. Moving the last row to the top moves all the others.
• "The two branches of a ternary are two different components." No. If both branches put the same type at the same place with the same key, React keeps the fiber and its state.
• "A new key on the same element just updates it." No. A different key means no old fiber matches, so React deletes the old one and creates a new one with fresh state.
• "React skips a child when its props are equal." Only when they are the same object. Without memo, beginWork compares the props objects with !==, and a new element always brings a new object.
• "useFiber is a hook." No. It's an internal helper in ReactChildFiber.js that reuses a fiber with new props.

Practice exercises

The exercises use the same watch.js report. Guess first, then press Edit & run to check.

import { useState } from "react";
import { useDomReport } from "./watch.js";

const groceries = [
  { id: "apple", name: "Apples" },
  { id: "bread", name: "Bread" },
  { id: "cheese", name: "Cheese" },
  { id: "dates", name: "Dates" },
];

export default function App() {
  const [items, setItems] = useState(groceries);
  const [listRef, report] = useDomReport();

  function swapFirstTwo() {
    setItems([items[1], items[0], ...items.slice(2)]);
  }

  return (
    <>
      <button onClick={swapFirstTwo}>Swap the first two</button>
      <ul ref={listRef}>
        {items.map((item) => (
          <li key={item.id}>{item.name}</li>
        ))}
      </ul>
      <ol className="report">
        {report.map((line) => (
          <li key={line}>{line}</li>
        ))}
      </ol>
    </>
  );
}

1import { useState } from "react";2import { useDomReport } from "./watch.js";3 4const groceries = [5  { id: "apple", name: "Apples" },6  { id: "bread", name: "Bread" },7  { id: "cheese", name: "Cheese" },8  { id: "dates", name: "Dates" },9];10 11export default function App() {12  const [items, setItems] = useState(groceries);13  const [listRef, report] = useDomReport();14 15  function swapFirstTwo() {16    setItems([items[1], items[0], ...items.slice(2)]);17  }18 19  return (20    <>21      <button onClick={swapFirstTwo}>Swap the first two</button>22      <ul ref={listRef}>23        {items.map((item) => (24          <li key={item.id}>{item.name}</li>25        ))}26      </ul>27      <ol className="report">28        {report.map((line) => (29          <li key={line}>{line}</li>30        ))}31      </ol>32    </>33  );34}

import { useState } from "react";

function NoteBox({ size }) {
  return <textarea rows={size === "big" ? 6 : 2} placeholder="Delivery notes" />;
}

export default function App() {
  const [expanded, setExpanded] = useState(false);
  return (
    <>
      <button onClick={() => setExpanded(!expanded)}>
        {expanded ? "Make it smaller" : "Make it bigger"}
      </button>
      <div>{expanded ? <NoteBox size="big" /> : <NoteBox size="small" />}</div>
    </>
  );
}

1import { useState } from "react";2 3function NoteBox({ size }) {4  return <textarea rows={size === "big" ? 6 : 2} placeholder="Delivery notes" />;5}6 7export default function App() {8  const [expanded, setExpanded] = useState(false);9  return (10    <>11      <button onClick={() => setExpanded(!expanded)}>12        {expanded ? "Make it smaller" : "Make it bigger"}13      </button>14      <div>{expanded ? <NoteBox size="big" /> : <NoteBox size="small" />}</div>15    </>16  );17}

1import { useState } from "react";2import { useDomReport } from "./watch.js";3 4const groceries = [5  { id: "apple", name: "Apples" },6  { id: "bread", name: "Bread" },7  { id: "cheese", name: "Cheese" },8  { id: "dates", name: "Dates" },9];10 11export default function App() {12  const [items, setItems] = useState(groceries);13  const [listRef, report] = useDomReport();14 15  return (16    <>17      <button onClick={() => setItems([items.at(-1), ...items.slice(0, -1)])}>Last to top</button>18      <ul ref={listRef}>19        {items.map((item, index) => (20          <li key={index}>21            <label>22              {item.name} <input size={3} />23            </label>24          </li>25        ))}26      </ul>27      <ol className="report">28        {report.map((line) => (29          <li key={line}>{line}</li>30        ))}31      </ol>32    </>33  );34}

1import { useState } from "react";2import { useDomReport } from "./watch.js";3 4const groceries = [5  { id: "apple", name: "Apples" },6  { id: "bread", name: "Bread" },7  { id: "cheese", name: "Cheese" },8  { id: "dates", name: "Dates" },9];10 11export default function App() {12  const [items, setItems] = useState(groceries);13  const [listRef, report] = useDomReport();14 15  return (16    <>17      <button onClick={() => setItems([items.at(-1), ...items.slice(0, -1)])}>Last to top</button>18      <ul ref={listRef}>19        {items.map((item, index) => (20          <li key={item.id}>21            <label>22              {item.name} <input size={3} />23            </label>24          </li>25        ))}26      </ul>27      <ol className="report">28        {report.map((line) => (29          <li key={line}>{line}</li>30        ))}31      </ol>32    </>33  );34}

1import { useState } from "react";2import { useDomReport } from "./watch.js";3 4export default function App() {5  const [compact, setCompact] = useState(false);6  const [cardRef, report] = useDomReport();7 8  return (9    <>10      <button onClick={() => setCompact(!compact)}>Switch the layout</button>11      <div ref={cardRef}>12        {compact ? (13          <section className="card compact">14            <h3>Delivery notes</h3>15            <textarea rows={2} />16          </section>17        ) : (18          <div className="card">19            <h3>Delivery notes</h3>20            <textarea rows={2} />21          </div>22        )}23      </div>24      <ol className="report">25        {report.map((line) => (26          <li key={line}>{line}</li>27        ))}28      </ol>29    </>30  );31}

1import { useState } from "react";2import { useDomReport } from "./watch.js";3 4export default function App() {5  const [compact, setCompact] = useState(false);6  const [cardRef, report] = useDomReport();7 8  return (9    <>10      <button onClick={() => setCompact(!compact)}>Switch the layout</button>11      <div ref={cardRef}>12        <div className={compact ? "card compact" : "card"}>13          <h3>Delivery notes</h3>14          <textarea rows={2} />15        </div>16      </div>17      <ol className="report">18        {report.map((line) => (19          <li key={line}>{line}</li>20        ))}21      </ol>22    </>23  );24}

// Which rows does React move? Follow reconcileChildrenArray:
// walk while the keys match, then use a map and lastPlacedIndex.
function movedRows(oldKeys, newKeys) {
  const moved = [];
  // Your code here.
  return moved;
}

const before = ["apple", "bread", "cheese", "dates"];
console.log(movedRows(before, ["dates", "apple", "bread", "cheese"]).join(", "));
console.log(movedRows(before, ["bread", "cheese", "dates", "apple"]).join(", "));

// Which rows does React move? Follow reconcileChildrenArray:
// walk while the keys match, then use a map and lastPlacedIndex.
function movedRows(oldKeys, newKeys) {
  const moved = [];
  let lastPlacedIndex = 0;
  let newIdx = 0;
  // The first pass: walk both lists while the keys match.
  while (newIdx < oldKeys.length && newIdx < newKeys.length && oldKeys[newIdx] === newKeys[newIdx]) {
    lastPlacedIndex = newIdx;
    newIdx++;
  }
  // The rest of the old list, in a map from key to old position.
  const existing = new Map();
  for (let i = newIdx; i < oldKeys.length; i++) existing.set(oldKeys[i], i);
  // The second pass: placeChild's rule.
  for (; newIdx < newKeys.length; newIdx++) {
    const oldIndex = existing.get(newKeys[newIdx]);
    if (oldIndex === undefined) continue; // A new row is inserted, not moved.
    if (oldIndex < lastPlacedIndex) moved.push(newKeys[newIdx]);
    else lastPlacedIndex = oldIndex;
  }
  return moved;
}

const before = ["apple", "bread", "cheese", "dates"];
console.log(movedRows(before, ["dates", "apple", "bread", "cheese"]).join(", "));
console.log(movedRows(before, ["bread", "cheese", "dates", "apple"]).join(", "));

1import { useState } from "react";2 3function ProductList() {4  console.log("ProductList renders");5  return (6    <ul>7      <li>Apples</li>8      <li>Bread</li>9    </ul>10  );11}12 13function Layout() {14  const [dark, setDark] = useState(false);15  return (16    <div className={dark ? "page dark" : "page"}>17      <button onClick={() => setDark(!dark)}>Switch theme</button>18      <ProductList />19    </div>20  );21}22 23export default function App() {24  return <Layout />;25}

1import { useState } from "react";2 3function ProductList() {4  console.log("ProductList renders");5  return (6    <ul>7      <li>Apples</li>8      <li>Bread</li>9    </ul>10  );11}12 13function Layout({ children }) {14  const [dark, setDark] = useState(false);15  return (16    <div className={dark ? "page dark" : "page"}>17      <button onClick={() => setDark(!dark)}>Switch theme</button>18      {children}19    </div>20  );21}22 23export default function App() {24  return (25    <Layout>26      <ProductList />27    </Layout>28  );29}

Check your understanding

For list questions, write the old indexes under the new order, then go left to right with lastPlacedIndex.

Key takeaways

• Reconciliation runs in beginWork, one level at a time: reconcileChildren compares what a component returned with its old child fibers. A mounting subtree uses mountChildFibers, which records no moves.
• Same key and same type: useFiber reuses the old fiber and its DOM node with new props. Anything else: createFiberFromElement makes a new fiber, and deleteChild puts the old one on the parent's deletions.
• A different type replaces the whole subtree. React never compares what's inside it, which keeps the pass fast.
• reconcileChildrenArray walks both lists while the keys match, then maps the rest of the old children by key. A reused child whose old index is below lastPlacedIndex gets Placement, so moving the last row to the top moves all the others.
• beginWork bails out of a fiber when its props object is the same and it has no update or context change; if no child has work either, the whole subtree is skipped.

Coming next: The commit phase. Reconciliation leaves flags like Placement and ChildDeletion on the fibers; the commit phase reads them and changes the DOM in one go.