Reconciliation and Diffing Algorithm

The Algorithm That Makes React Possible

When you call setState, React doesn't throw away the DOM and rebuild it. It compares the new element tree against the old one and figures out the minimum set of DOM operations needed. This comparison is the reconciliation algorithm.

A general tree diff is O(n^3) — for 1,000 nodes, that's a billion comparisons. React does it in O(n) with two heuristics that turn out to be correct 99.9% of the time.

// Before: React sees this tree
<div>
  <Header />
  <UserList users={oldUsers} />
</div>

// After setState: React sees this tree
<div>
  <Header />
  <UserList users={newUsers} />
</div>

// React's diff:
// 1. <div> === <div> → same type → keep DOM node, check children
// 2. <Header> === <Header> → same type → compare props (none changed → skip)
// 3. <UserList> === <UserList> → same type → compare props (users changed → re-render)

The Mental Model

Heuristic 1: Same Type = Update, Different Type = Destroy

React compares elements at the same position in the tree. The first check is always the element type:

// Same type: React updates the existing DOM node
// Before:
<div className="old" />
// After:
<div className="new" />
// React: Keep the DOM node. Change className from "old" to "new".

// Different type: React destroys the old tree and builds new
// Before:
<div><Counter /></div>
// After:
<span><Counter /></span>
// React: Destroy the entire <div> subtree (including Counter's state).
//        Build a fresh <span> subtree. Counter starts from initial state.

This has a critical implication: changing the wrapper element destroys all child state.

function App({ isAdmin }) {
  // Every time isAdmin changes, Counter loses its state
  if (isAdmin) {
    return <section><Counter /></section>;
  }
  return <div><Counter /></div>;
}

React sees <section> change to <div>. Different types. It unmounts the entire <section> subtree and mounts a fresh <div> subtree. Counter's state resets to 0.

Component Type Identity

For components, React compares the function/class reference itself:

// These are different components even though they render identical output
const ButtonA = () => <button>Click</button>;
const ButtonB = () => <button>Click</button>;

function App({ useNew }) {
  // Toggling between ButtonA and ButtonB destroys and remounts
  return useNew ? <ButtonA /> : <ButtonB />;
}

React checks ButtonA === ButtonB — they're different function references, so the old fiber is destroyed and a new one is created.

function App() {
  // BUG: This creates a new component type on every render
  const Input = () => <input />;
  return <Input />; // Unmounts and remounts every render — loses focus, loses input
}

Heuristic 2: Keys Identify Elements in Lists

When React encounters a list of children, it can't rely on position alone. Consider reordering:

// Before:
<ul>
  <li>Alice</li>
  <li>Bob</li>
  <li>Charlie</li>
</ul>

// After (Alice removed):
<ul>
  <li>Bob</li>
  <li>Charlie</li>
</ul>

Without keys, React compares by position:

• Position 0: Alice → Bob. Same type <li>. React updates text from "Alice" to "Bob".
• Position 1: Bob → Charlie. Same type <li>. React updates text from "Bob" to "Charlie".
• Position 2: Charlie → nothing. React removes the third <li>.

Result: three DOM operations (two text updates + one removal). But the optimal answer is one operation: remove Alice's <li>.

With keys:

<ul>
  <li key="alice">Alice</li>
  <li key="bob">Bob</li>
  <li key="charlie">Charlie</li>
</ul>
// After:
<ul>
  <li key="bob">Bob</li>
  <li key="charlie">Charlie</li>
</ul>

React matches by key: Bob's <li> stays, Charlie's <li> stays, Alice's <li> is removed. One DOM operation.

The List Reconciliation Algorithm

The actual algorithm is more nuanced than simple key matching. If you want to know exactly what happens when React processes your list, here it is:

For the new list of children:
1. Build a map: oldKey → oldFiber for all existing children
2. For each new child:
   a. Look up its key in the map
   b. If found: reuse the old fiber, update props, remove from map
   c. If not found: create a new fiber (Placement flag)
   d. Track whether the reused fiber needs to move (its old index < lastPlacedIndex)
3. Any remaining fibers in the map are deletions (Deletion flag)

The lastPlacedIndex optimization avoids unnecessary moves: items that are already in the right relative order stay put. Only items that moved backward (relative to the previous iteration) get repositioned.

DOM Operation Flags

During reconciliation, React doesn't touch the DOM. Instead, it tags fibers with effect flags:

// Effect flags set during reconciliation
const Placement = 0b0000000000000010;    // New node — insert into DOM
const Update =    0b0000000000000100;    // Props changed — update DOM attributes
const Deletion =  0b0000000000001000;    // Removed — delete from DOM
const ChildDeletion = 0b0000000000010000; // A child was deleted

These flags accumulate during the render phase. The commit phase reads them and performs the actual DOM mutations in a single batch.

Production Scenario: The Expensive Remount

A team has a tabbed interface where each tab renders a complex form:

function TabbedForm({ activeTab }) {
  // BUG: Different wrapper elements destroy child state
  switch (activeTab) {
    case 'basic':
      return <div className="tab-basic"><BasicForm /></div>;
    case 'advanced':
      return <section className="tab-advanced"><AdvancedForm /></section>;
    case 'admin':
      return <article className="tab-admin"><AdminForm /></article>;
  }
}

Every tab switch destroys the form state because the wrapper element type changes (div → section → article). Users lose their in-progress form data.

The fix uses the same element type with different props:

function TabbedForm({ activeTab }) {
  return (
    <div className={`tab-${activeTab}`}>
      {activeTab === 'basic' && <BasicForm />}
      {activeTab === 'advanced' && <AdvancedForm />}
      {activeTab === 'admin' && <AdminForm />}
    </div>
  );
}

Now the wrapper is always <div>. React updates the className prop without destroying children. But each form still unmounts when its tab isn't active — sometimes that's desired (reset on switch), sometimes not.

For preserving state across tabs, use CSS visibility or display: none, or lift state out of the form components.

Common Mistakes

Challenge

Predict the DOM operations

1. **Destroy `<h1>` and create `<h2>`** — `h1` → `h2` is a type change. React removes the `<h1>` node and creates a new `<h2>` with text "New Title".

2. **Update `<p>` text content** — Same type `<p>`, same key "intro". React updates the text from "Welcome!" to "Hello!". No DOM removal.

Quiz

Key Rules