Skip to main content
Reconciliation is the algorithm React uses to diff one tree with another to determine which parts need to be changed. It’s the process that makes Virtual DOM updates efficient.

​
Key-based reconciliation

Keys are the primary mechanism React uses to identify which items have changed, been added, or removed in a list.
1

Without keys

React compares elements position-by-position. Moving an item requires destroying and recreating elements, losing component state.
2

With keys

React uses keys to match elements between renders. Elements can be reordered efficiently while preserving component instances and state.

​
Key requirements

Keys must be stable, predictable, and unique among siblings. Using array indices as keys can cause subtle bugs when items are reordered or removed.
// Bad - using index as key
{items.map((item, index) => (
  <Item key={index} data={item} />
))}

// Good - using stable identifier
{items.map((item) => (
  <Item key={item.id} data={item} />
))}

​
Reconciliation heuristics

React implements three core heuristics to achieve O(n) complexity:

​
1. Component type heuristic

Elements of different component types produce fundamentally different trees.
When React encounters different component types at the same position, it unmounts the old tree completely and builds a new one from scratch—no attempt to diff.
// Before render
<Counter count={5} />

// After render - complete replacement
<Timer seconds={5} />
This means:
  • The old Counter component is unmounted
  • Its state is destroyed
  • The Timer component is mounted fresh
  • All child components are recreated

​
2. Element type heuristic

Similar to components, different element types trigger a rebuild. 
// Before
<div className="container">
  <span>Hello</span>
</div>

// After - div→article triggers rebuild
<article className="container">
  <span>Hello</span>
</article>
Even though the structure seems similar, React will:
  1. Unmount the div and its children
  2. Create new DOM nodes for article and its children
  3. Mount the new tree

​
3. List reconciliation heuristic

For lists of children, React uses keys to match elements.
1

Building a key map

React builds a map of keys to elements in the old list for O(1) lookups.
2

Processing new list

For each element in the new list, React checks if a matching key exists in the old list.
3

Reuse or create

If a key matches, reuse and update the element. If not, create a new one.
4

Cleanup

Any old elements not matched in the new list are unmounted.

​
Performance implications

ScenarioWithout KeysWith Keys
Add item to startO(n) unmount + mountO(1) insert
Remove itemO(n) DOM operationsO(1) remove
Reorder itemsO(n) destroy + recreateO(n) move operations
Update one itemO(n) comparisonO(1) lookup + update
While keys dramatically improve list performance, they have overhead. Only use keys for dynamic lists—static lists can rely on position-based reconciliation.

​
Fiber architecture preparation

The reconciliation heuristics lay the groundwork for React’s Fiber architecture, which adds:
  • Interruptible work: Break reconciliation into units that can be paused
  • Priority-based updates: Handle different updates with different urgency
  • Incremental rendering: Spread work across multiple frames
  • Better error boundaries: Catch and handle errors during reconciliation
Fiber doesn’t change the reconciliation heuristics—it changes when and how reconciliation work is scheduled and executed.

​
Implementation guidelines

When implementing a reconciliation algorithm:
  1. Build the heuristics first: Get component type, element type, and list reconciliation working
  2. Profile extensively: Measure both JavaScript execution time and DOM operation counts
  3. Handle edge cases: Fragments, portals, null, boolean, and array children
  4. Prepare for scheduling: Structure your reconciliation work to be pausable
In the Week 6 project, these heuristics form the core of your Virtual DOM library’s reconciliation algorithm, which you’ll stress test with 10,000+ dynamic nodes.

​
Next steps

With reconciliation heuristics in place, the next challenge is coordinating when updates happen—batching multiple state changes together and scheduling them efficiently with requestAnimationFrame.

Build docs developers (and LLMs) love

Get started for freeTalk to us