Reconciliation

Notes from the legacy React docs page Reconciliation, react.dev’s Preserving and Resetting State, and the React 19.2 source (updateElement, updateSlot, useFiber). Part of React Internals. It follows Render and Commit, and the list algorithm itself is in Child Reconciliation Algorithm. My own notes and clarifications are marked with > 💬.

Interview Q&A

The problem: diffing two trees is expensive

A component returns a tree of elements. On the next render it returns another. React has to turn “old tree” into “new tree” with as few DOM operations as possible. Solving that minimum edit distance between two arbitrary trees is O(n³), which the legacy docs call “far too expensive”. A UI with 1,000 elements would take about a billion comparisons per update.

React gives up on finding the minimal set of edits and settles for a good-enough one found in a single top-down pass. Each node is compared only with the node at the same position in the previous tree. React never searches the tree to see whether a subtree moved somewhere else. That makes it O(n), and two rules make the result good in practice.

Rule 1: different type → throw away the subtree

When an element at a position has a different type than last time, React does not try to match up the children. The legacy docs: “Whenever the root elements have different types, React will tear down the old tree and build the new tree from scratch.”

// before                 // after
<div>                     <span>
	<Counter />               <Counter />
</div>                    </span>

Counter looks identical, but its parent changed from div to span, so the old Counter is unmounted, meaning its state is destroyed and its effect cleanups run. A brand-new Counter is mounted. The same happens for component types: <Article /> → <Comment /> at the same spot remounts.

In the source this is the check in updateElement (for list children) and reconcileSingleElement (for a single child, inlined into reconcileChildFibersImpl in the build), in simplified form:

if (current !== null && current.elementType === element.type) {
	// same type: reuse the fiber (and its state and DOM node), only props change
	const existing = useFiber(current, element.props)
	existing.return = returnFiber
	return existing
}
// different type (or nothing there before): create a new fiber
const created = createFiberFromElement(element, returnFiber.mode, lanes)
created.return = returnFiber
return created

useFiber calls createWorkInProgress(current, pendingProps), which returns the alternate of the existing fiber with the new props. That’s why state survives: the hooks list lives on the fiber (see React Fiber and Hooks Under the Hood).

Rule 2: same type → keep it and update

Same host element (<div> → <div>): the fiber and its DOM node are kept. The render phase flags the fiber Update if it got a new props object. The commit (commitUpdate) then compares old and new props and touches only the attributes that changed. The legacy docs’ example: going from <div className="before" title="stuff" /> to <div className="after" title="stuff" />, “React knows to only modify the className on the underlying DOM node.” For style, only the changed style properties are updated.

Same component type: the fiber is kept, so hooks and state are preserved. React calls the component with the new props (unless it can bail out, see The Work Loop) and then reconciles its output against the old children, going down level by level.

Rule 3: keys identify children in a list

When a fiber has several children, React has to pair each new child with an old one. Without keys it pairs them by index. The legacy docs’ example shows why that breaks when inserting at the front:

<ul>                           <ul>
	<li>Duke</li>                  <li>Connecticut</li>   ← index 0: "Duke" fiber, text changed
	<li>Villanova</li>             <li>Duke</li>          ← index 1: "Villanova" fiber, text changed
</ul>                            <li>Villanova</li>     ← index 2: new fiber
                               </ul>

“React will mutate every child instead of realizing it can keep the <li>Duke</li> and <li>Villanova</li> subtrees intact.” With keys, React matches children by key instead, so it keeps both existing items and inserts one new node. The exact matching algorithm (a fast path in order, then a Map of the remaining keys, then deciding which nodes have to move) is covered in Child Reconciliation Algorithm.

react.dev adds that keys are local: “Keys are not globally unique. They only specify the position within the parent.”

What this means for your code: state is tied to position

react.dev’s rule: “React keeps track of which state belongs to which component based on their place in the UI tree.” A few consequences follow from that.

It’s the tree position, not where the JSX is written. These two branches render Counter at the same position (first child of a div), so state is preserved when isFancy flips:

if (isFancy) {
	return (
		<div>
			<Counter isFancy={true} />
		</div>
	)
}
return (
	<div>
		<Counter isFancy={false} />
	</div>
)

react.dev: “It’s the position in the UI tree—not in the JSX markup—that matters to React!”

Different type at the same position resets state:

{isPaused ? <p>See you later!</p> : <Counter />}

Two ways to force a reset when the same component shows different things:

// 1. different positions: two separate slots, only one filled at a time
{isPlayerA && <Counter person="Taylor" />}
{!isPlayerA && <Counter person="Sarah" />}

// 2. different keys at the same position
{isPlayerA ? (
	<Counter key="Taylor" person="Taylor" />
) : (
	<Counter key="Sarah" person="Sarah" />
)}

Option 1 works because {cond && <X/>} leaves a false hole in the children array. The two counters are children #0 and #1, never the same index. That’s also why conditional rendering with && doesn’t shift the positions of siblings that come after it.

Components defined inside components remount every render:

function MyComponent() {
	function MyTextField() {   // a NEW function on every render of MyComponent
		const [text, setText] = useState('')
		return <input value={text} onChange={(e) => setText(e.target.value)} />
	}
	return <MyTextField />
}

element.type is a new function each time, so current.elementType === element.type is false and Rule 1 applies. The input loses its text and focus on every keystroke. Define components at module level.

Reconciliation, step by step

App re-renders after setShowBanner(false):

// previous render                // this render
<main>                            <main>
	<Banner />                        {false}
	<Header title="Hi" />             <Header title="Hi!" />
	<ul>                              <ul>
		<li key="a">A</li>                <li key="b">B</li>
		<li key="b">B</li>                <li key="a">A</li>
	</ul>                             </ul>
</main>                           </main>

The render phase only records these decisions as flags (ChildDeletion, Placement, Update). The commit phase applies them (Commit Phase and Effects).

Rules and caveats

• Type identity matters. Don’t create components (or memo/lazy wrappers) during render. Hoist them to module scope.
• Keys must be stable, predictable and unique among siblings. The legacy docs warn that unstable keys “(like those produced by Math.random()) will cause many component instances and DOM nodes to be unnecessarily recreated, which can cause performance degradation and lost state in child components.”
• Index keys are fine only for static lists. If items are inserted, removed or reordered, state and DOM (inputs, focus) stick to the wrong item.
• Use key to reset on purpose. <Profile key={userId} /> is the idiomatic way to discard all state when the identity changes, instead of syncing it in an effect.
• Wrapping changes the position. Adding a <div> or a <Suspense> around a component changes its parent type, and it remounts.

Sources

• Legacy React docs: Reconciliation
• react.dev: Preserving and Resetting State
• Andrew Clark: React Fiber Architecture
• React 19.2.5 source: updateElement, updateSlot, useFiber, createWorkInProgress

Primary source: legacy.reactjs.org/docs/reconciliation.html