Virtual DOM Explained: How React Avoids Costly DOM Updates

// Simulates updating a large list — once naively, once with batching.
// Run this in a browser console with a <ul id="item-list"> in the HTML.

const listElement = document.getElementById('item-list');

// Helper: generate 500 raw list items
function generateItems(count) {
  return Array.from({ length: count }, (_, index) => `Item ${index + 1}`);
}

// ─── APPROACH 1: Naive — one DOM write per item ───────────────────────────────
function renderListNaively(items) {
  listElement.innerHTML = ''; // clear existing content

  const startTime = performance.now();

  items.forEach((itemText) => {
    const listItem = document.createElement('li');
    listItem.textContent = itemText;
    listElement.appendChild(listItem); // triggers reflow on every append
  });

  const endTime = performance.now();
  console.log(`Naive render: ${(endTime - startTime).toFixed(2)}ms`);
}

// ─── APPROACH 2: Batched — build off-screen, one DOM write total ──────────────
function renderListBatched(items) {
  listElement.innerHTML = ''; // clear existing content

  const startTime = performance.now();

  // DocumentFragment lives in memory — NOT attached to the live DOM
  const fragment = document.createDocumentFragment();

  items.forEach((itemText) => {
    const listItem = document.createElement('li');
    listItem.textContent = itemText;
    fragment.appendChild(listItem); // no reflow — fragment is off-screen
  });

  listElement.appendChild(fragment); // ONE reflow for the whole batch

  const endTime = performance.now();
  console.log(`Batched render: ${(endTime - startTime).toFixed(2)}ms`);
}

const items = generateItems(500);

renderListNaively(items);
renderListBatched(items);

// A minimal Virtual DOM implementation — shows the three steps:
// 1. Create virtual nodes (vnode)
// 2. Mount them to real DOM
// 3. Diff old vs new, patch only what changed

// ─── STEP 1: Define what a virtual node looks like ────────────────────────────
// A vnode is just a plain JS object — not a real DOM node.
function createElement(type, props, ...children) {
  return {
    type,                         // e.g. 'div', 'li', 'button'
    props: props || {},           // e.g. { className: 'active', id: 'main' }
    children: children.flat(),    // nested vnodes or plain text strings
  };
}

// ─── STEP 2: Turn a vnode into a real DOM node and mount it ──────────────────
function mount(vnode, container) {
  // Text nodes — leaf of the tree
  if (typeof vnode === 'string' || typeof vnode === 'number') {
    const textNode = document.createTextNode(vnode);
    container.appendChild(textNode);
    return textNode;
  }

  const domElement = document.createElement(vnode.type);

  // Apply all props as DOM attributes/properties
  Object.entries(vnode.props).forEach(([propName, propValue]) => {
    domElement.setAttribute(propName, propValue);
  });

  // Recursively mount each child
  vnode.children.forEach((child) => mount(child, domElement));

  container.appendChild(domElement);
  return domElement;
}

// ─── STEP 3: Diff two vnodes — patch only what's different ───────────────────
function patch(domNode, oldVnode, newVnode) {
  // Case A: new vnode is plain text — just update the text content
  if (typeof newVnode === 'string' || typeof newVnode === 'number') {
    if (newVnode !== oldVnode) {
      domNode.textContent = newVnode; // single targeted update
    }
    return domNode;
  }

  // Case B: element type changed entirely (e.g. <div> → <section>)
  // React's rule: different types = tear down and rebuild
  if (oldVnode.type !== newVnode.type) {
    const freshNode = mount(newVnode, document.createElement('div'));
    domNode.parentNode.replaceChild(freshNode, domNode);
    return freshNode;
  }

  // Case C: same element type — update only changed props
  const oldProps = oldVnode.props;
  const newProps = newVnode.props;

  // Remove props that no longer exist
  Object.keys(oldProps).forEach((propName) => {
    if (!(propName in newProps)) {
      domNode.removeAttribute(propName);
    }
  });

  // Add or update props that are new or changed
  Object.entries(newProps).forEach(([propName, propValue]) => {
    if (oldProps[propName] !== propValue) {
      domNode.setAttribute(propName, propValue); // only fires if value changed
    }
  });

  // Recursively patch children
  const maxChildCount = Math.max(
    oldVnode.children.length,
    newVnode.children.length
  );

  for (let i = 0; i < maxChildCount; i++) {
    const oldChild = oldVnode.children[i];
    const newChild = newVnode.children[i];

    if (oldChild === undefined) {
      // New child that didn't exist before — mount it
      mount(newChild, domNode);
    } else if (newChild === undefined) {
      // Old child no longer needed — remove it
      domNode.removeChild(domNode.childNodes[i]);
    } else {
      // Both exist — recurse into them
      patch(domNode.childNodes[i], oldChild, newChild);
    }
  }

  return domNode;
}

// ─── DEMO: Show the diff in action ───────────────────────────────────────────
const appContainer = document.getElementById('app');

// Initial render — like a component's first paint
const initialVnode = createElement(
  'div',
  { class: 'user-card' },
  createElement('h2', {}, 'Alice'),
  createElement('p', { class: 'status' }, 'Offline')
);

const realDomNode = mount(initialVnode, appContainer);
console.log('Mounted initial vnode — DOM now has .user-card with Alice + Offline');

// State change — only the status text changed, nothing else
const updatedVnode = createElement(
  'div',
  { class: 'user-card' },
  createElement('h2', {}, 'Alice'),           // unchanged
  createElement('p', { class: 'status active' }, 'Online') // class + text changed
);

patch(realDomNode, initialVnode, updatedVnode);
console.log('Patched — only the <p> class and text were touched in the real DOM');

// This is React JSX — run it in a CodeSandbox or Vite+React project.
// It demonstrates WHY keys exist by showing the bug without them.

import { useState } from 'react';

// ─── BAD EXAMPLE: No keys on a dynamic list ───────────────────────────────────
// When you prepend a new task, React reuses the first DOM node
// for the new item but keeps the existing <input> values in place.
// Result: the checkbox/input state shifts to the wrong item.
function TaskListWithoutKeys() {
  const [tasks, setTasks] = useState([
    { id: 1, label: 'Write tests' },
    { id: 2, label: 'Review PR' },
  ]);

  function prependUrgentTask() {
    // Insert at the TOP of the list
    setTasks([
      { id: 3, label: '🔥 Fix production bug' },
      ...tasks,
    ]);
  }

  return (
    <div>
      <h3>Without Keys (broken)</h3>
      <button onClick={prependUrgentTask}>Add urgent task at top</button>
      <ul>
        {tasks.map((task) => (
          // ❌ No key — React uses array index as identity by default
          <li>
            <input type="checkbox" />
            {/* Input state WILL NOT move with the item when list reorders */}
            <span>{task.label}</span>
          </li>
        ))}
      </ul>
    </div>
  );
}

// ─── GOOD EXAMPLE: Stable, unique keys ────────────────────────────────────────
// React uses task.id to match old and new nodes.
// When you prepend, the existing <li> nodes for id=1 and id=2 are MOVED
// in the DOM — their input state travels with them correctly.
function TaskListWithKeys() {
  const [tasks, setTasks] = useState([
    { id: 1, label: 'Write tests' },
    { id: 2, label: 'Review PR' },
  ]);

  function prependUrgentTask() {
    setTasks([
      { id: 3, label: '🔥 Fix production bug' },
      ...tasks,
    ]);
  }

  return (
    <div>
      <h3>With Keys (correct)</h3>
      <button onClick={prependUrgentTask}>Add urgent task at top</button>
      <ul>
        {tasks.map((task) => (
          // ✅ key uses the stable, unique task ID
          <li key={task.id}>
            <input type="checkbox" />
            {/* Checkbox state correctly stays with its task after reorder */}
            <span>{task.label}</span>
          </li>
        ))}
      </ul>
    </div>
  );
}

export default function App() {
  return (
    <>
      <TaskListWithoutKeys />
      <hr />
      <TaskListWithKeys />
    </>
  );
}

// ─── HOW TO SEE THE BUG ───────────────────────────────────────────────────────
// 1. Tick the checkbox next to 'Write tests' in BOTH lists.
// 2. Click 'Add urgent task at top' in BOTH lists.
// Without keys: the tick jumps to '🔥 Fix production bug' — WRONG.
// With keys:    the tick stays on 'Write tests'            — CORRECT.

// This isn't a runnable demo — it's annotated pseudocode that maps
// real-world scenarios to the right tool.

// ─── SCENARIO 1: High-frequency updates, many components ─────────────────────
// e.g. A stock ticker updating 50 rows every 500ms
//
// ✅ Use React / Virtual DOM
// Why: React batches all 50 row updates into one reconciliation pass.
//      Without it, you'd trigger 50 individual reflows.

function StockTickerRow({ symbol, price, change }) {
  // React only re-renders this component if its props actually changed.
  // If AAPL price didn't move this tick, this component is skipped entirely.
  return (
    <tr className={change >= 0 ? 'price-up' : 'price-down'}>
      <td>{symbol}</td>
      <td>{price.toFixed(2)}</td>
      <td>{change > 0 ? `+${change}` : change}</td>
    </tr>
  );
}

// ─── SCENARIO 2: Simple one-time DOM manipulation ─────────────────────────────
// e.g. A 'copy to clipboard' button that flashes 'Copied!' for 2 seconds
//
// ✅ Use vanilla JS — no framework needed
// Why: One button, one attribute change, one timeout. A Virtual DOM
//      layer would add ~45kb of library overhead for a 3-line job.

const copyButton = document.getElementById('copy-btn');

copyButton.addEventListener('click', async () => {
  await navigator.clipboard.writeText(document.getElementById('code-snippet').textContent);

  copyButton.textContent = 'Copied!';
  copyButton.setAttribute('disabled', 'true');

  setTimeout(() => {
    copyButton.textContent = 'Copy';
    copyButton.removeAttribute('disabled');
  }, 2000);
  // Direct DOM mutation is perfectly fine here — it's two writes, total.
});

// ─── SCENARIO 3: Svelte's approach — no virtual DOM, compiled updates ─────────
// Svelte turns this component template:
//
//   <p>{userName}</p>
//
// ...into this compiled output at build time:
//
//   // Compiled by Svelte — no diff, no virtual tree:
//   function update(changed, ctx) {
//     if (changed.userName) {
//       setData(paragraphNode, ctx.userName); // single surgical DOM write
//     }
//   }
//
// No runtime diffing — the compiler already knows exactly what can change.
// This beats Virtual DOM on small updates, matches it on large ones.

console.log('See comments above for scenario analysis');