🧠 React Internals — Behind the Scenes

Everything in this guide is really about one pipeline: you change some state, and React turns that into the smallest possible update to the screen. Here's the whole journey on one line — keep this picture in mind as you read.

🔑 Glossary — the jargon in plain language

Quick, layman one-liners. Each is unpacked properly in the sections below.

The world before React: imperative DOM

In vanilla JS you don't describe what the UI should look like — you describe the steps to mutate it. You are personally responsible for the transition between every possible state and every other state.

function addMessage(msg) {
  messages.push(msg);
  // YOU manually keep the DOM in sync:
  countEl.textContent = messages.length;
  const li = document.createElement('li');
  li.textContent = msg.text;
  if (msg.unread) li.classList.add('unread');
  listEl.appendChild(li);
}

This produces three compounding pains:

• State lives in two places — your JS variables and the DOM — and they drift out of sync. Most "weird UI bugs" are really sync bugs.
• Complexity is O(transitions), not O(states). With N pieces of state, the ways to move between them explode. jQuery apps collapsed under this.
• It's not composable. A widget's correctness depends on every call site updating it correctly.

React's core insight

UI = f(state)

You write the destination ("given this state, the UI looks like this"), never the path. This collapses the O(transitions) problem back to O(states) — you only ever reason about "what does the UI look like in this state."

function Messages({ messages }) {
  return (
    <>
      <span>{messages.length}</span>
      <ul>
        {messages.map(m => (
          <li className={m.unread ? 'unread' : ''}>{m.text}</li>
        ))}
      </ul>
    </>
  );
}

The model / execution split — this IS React

The obvious objection: "Re-run everything and rebuild the DOM on every keystroke? The DOM is slow!" Correct. So React splits the idea into two layers:

"The DOM is slow" isn't about the data structure — reading/writing a JS property is fast. What's expensive is that certain DOM operations force the browser to redo parts of its rendering pipeline synchronously.

The browser rendering pipeline

1. JS — your code runs, possibly mutating the DOM/CSSOM.
2. Style (recalc) — which CSS rules apply to which elements.
3. Layout (reflow) — compute geometry (x/y/width/height) of every affected box. The expensive one.
4. Paint — fill in pixels (text, colors, borders) into layers.
5. Composite — GPU assembles painted layers into the final image.

The stages are dependent and mostly sequential — the earlier the stage you dirty, the more downstream work you trigger:

This is exactly why "animate transform/opacity, not top/width" exists — those skip Layout and Paint and run on the compositor.

Forced (synchronous) reflow vs deferred reflow — the silent killer

Interleaving reads and writes turns one reflow into N — layout thrashing:

for (const el of boxes) {
  const w = el.offsetWidth;     // READ → forces reflow
  el.style.width = (w*2) + 'px';// WRITE → dirties layout
}
// read forces reflow, write dirties,
// next read forces reflow again...

const widths = boxes.map(el => el.offsetWidth); // all reads
boxes.forEach((el, i) =>
  el.style.width = widths[i]*2 + 'px');        // all writes
// reads never interleave with writes →
// browser coalesces into ONE reflow

How React attacks this

• Diff in JS, write to the DOM in one coordinated phase. Reconciliation runs against the VDOM (no layout cost); the commit phase applies all mutations together. React owns the write phase, so reads/writes don't interleave randomly across your codebase.
• Batching state updates. Multiple setState calls collapse into one re-render + one commit + one reflow. (React 18 made this automatic everywhere — that release note is really a reflow-minimization story.)
• Minimal mutations. The diff means React touches only changed nodes, keeping the reflow scope small.

A component is a function that produces a description

JSX is not magic. <button className="primary">Save</button> compiles to a function call returning a plain JS object — a React element:

{
  type: 'button',                 // string for host, function for a component
  props: { className: 'primary', children: 'Save' },
  key: null,
}

The full flow: setState → screen

• Render ≠ DOM update. Steps 2–3 are pure JS, no reflow. Only commit touches the DOM. "Re-rendered 40 times" with identical output commits nothing.
• Rendering is recursive, top-down. A re-render re-runs children too; reconciliation then usually finds "same as before." memo is an escape hatch to skip that.
• setState is a request, not a command. It schedules. This gap is where React 18's concurrency lives.

The two trees (double buffering)

Reconciliation diffs WIP against current; commit swaps WIP to become current. The current tree is untouched until commit — which is why concurrent mode can throw away an in-progress render without corrupting the screen.

Is setState async? The classic puzzle

function handleClick() {
  setCount(count + 1);
  setCount(count + 1);
  setCount(count + 1);
  console.log(count); // prints 0 — and the screen shows 1, not 3
}

The fix when next state depends on previous — pass a function, not a value:

setCount(prev => prev + 1);  // 0 → 1
setCount(prev => prev + 1);  // 1 → 2
setCount(prev => prev + 1);  // 2 → 3   (still ONE render)

Batch boundaries: React 17 → 18

Opting out: flushSync(() => setX(...)) forces a synchronous render+commit when you must read layout between updates. Rare, and it costs extra reflows.

Comparing two arbitrary trees for the minimal edit set is O(n³) — unusable. React doesn't solve the general problem; it cheats with two heuristics that drop it to O(n), accepting occasionally-non-minimal DOM work. Those two heuristics are reconciliation.

Heuristic 1: different type ⇒ throw the subtree away

At each position, React asks first: is type the same?

• Same host type ('div'): keep the DOM node, patch changed attributes, recurse into children.
• Same composite type (a component): keep the instance — preserve its state and hooks — feed new props, re-render.
• Different type ('div'→'span', A→B): tear down the entire old subtree (unmount, run cleanups, destroy DOM) and build the new one from scratch.

Heuristic 2: key gives identity within a list

Heuristic 1 compares by position. For lists that reorder/insert/delete, position-matching is catastrophic. key lets React match by identity, not slot.

{items.map((it, i) =>
  <li key={i}>...</li>)}

// prepend Z: key 0 was A, now "is" Z
// → React patches A→Z, B→A, adds C
// → an input's text sticks to the
//   SLOT, not the data. Wrong row!

{items.map(it =>
  <li key={it.id}>...</li>)}

// prepend Z: A and B keys unchanged
// → React inserts ONE node at front,
//   leaves A & B (and their state) alone.

The precise "same element" rule

old & new match as the SAME instance  ⟺
        same position in parent  AND  same `type`  AND  same `key`

This one rule explains: why moving a component between parents remounts it; why cond ? <A/> : <B/> with different types loses state; why two sibling same-type elements in the same slot surprisingly preserve state.

The problem: the stack reconciler couldn't pause

Pre-16 React used the stack reconciler — plain recursion that walked the tree depth-first. The fatal property: recursion uses the JS call stack, and you cannot pause a call stack. JS is single-threaded with run-to-completion semantics — once a deep recursion starts, it runs to the end before the browser can paint or handle input. A large update = a 50–200ms freeze.

React wanted to pause mid-render, resume, prioritize (urgent keystroke before expensive list), and abort stale work. None of that is possible with the call stack as the work queue.

The fix: reify the stack as a linked list on the heap

fiber = {
  type, key,            // same identity fields as the element (Heuristic 1 & 2)
  stateNode,            // the real DOM node, or class instance
  memoizedState,        // hooks list (useState/useEffect chain) / class state
  memoizedProps, pendingProps,

  // the tree, as POINTERS (a linked list, not a children array):
  child,                // first child
  sibling,              // next sibling
  return,               // parent ("return address", like a stack frame)

  alternate,            // link to this fiber's counterpart in the OTHER tree
  flags,                // effect tags: Placement / Update / Deletion
  lanes,                // priority of pending work
}

• child/sibling/return replace recursion: a depth-first walk done with a while loop over pointers — and a loop, unlike recursion, can stop after any step and resume later.
• alternate implements the two trees (double buffering). Building WIP never mutates current, so an aborted render just drops WIP — screen stays valid. Commit swaps root.current = workInProgress atomically.

Two phases, very different rules

The work loop & time slicing

function workLoop(deadline) {
  while (nextUnitOfWork && !shouldYield()) {
    nextUnitOfWork = performUnitOfWork(nextUnitOfWork); // do ONE fiber, return next
  }
  if (nextUnitOfWork) scheduleResume(workLoop); // more to do → yield, resume later
  else commitRoot();                            // tree done → commit
}

After each fiber, React checks shouldYield() (~5ms slice used up? more urgent work?). If yes, it breaks the loop and hands the thread back to the browser, then resumes from nextUnitOfWork later. That's time slicing.

The actual resume mechanism is React's Scheduler, built on MessageChannel (not setTimeout): postMessage schedules a macrotask that runs after the browser paints/handles input, without setTimeout's ~4ms clamp.

A minimal JS model of the work loop

JS has no built-in linked list, but an object holding references to other objects is one. Here's Fiber's traversal in ~30 lines:

// A "fiber" is just an object with pointers to other fibers
function fiber(name, children = []) {
  return { name, child: null, sibling: null, return: null, children };
}
function link(node) {                  // build child/sibling/return links
  let prev = null;
  for (const c of node.children) {
    c.return = node;
    if (!prev) node.child = c; else prev.sibling = c;
    prev = c; link(c);
  }
  return node;
}
const root = link(fiber('App', [
  fiber('Header', [fiber('Logo'), fiber('Nav')]),
  fiber('Main',   [fiber('List')]),
]));

let nextUnitOfWork = root;             // the BOOKMARK — a module-level variable

function performUnitOfWork(f) {        // do ONE fiber, return the NEXT (DFS)
  console.log('work:', f.name);
  if (f.child) return f.child;         // go down
  let node = f;
  while (node) {
    if (node.sibling) return node.sibling; // go right
    node = node.return;                    // go up, then try sibling
  }
  return null;
}
function workLoop() {
  let budget = 2;                      // pretend "5ms" = 2 nodes per slice
  while (nextUnitOfWork && budget-- > 0) {
    nextUnitOfWork = performUnitOfWork(nextUnitOfWork);
  }
  if (nextUnitOfWork) {
    console.log('  ⏸ yield (bookmark =', nextUnitOfWork.name, ')');
    setTimeout(workLoop, 0);           // stand-in for MessageChannel
  } else console.log('  ✅ done → commit');
}
workLoop();

Priority: lanes & concurrency

React 18 tags each update with priority as bitmask lanes. Urgent updates (clicks, typing) get high-priority lanes; startTransition/useDeferredValue get low-priority transition lanes. The scheduler renders urgent lanes first and can interrupt & restart an in-progress low-priority render.

typing in a box that filters a 10k list:
  keystroke   → urgent lane     → renders the input immediately
  list filter → transition lane → rendered in slices, interruptible,
                                   restarted if you keep typing → no jank

How does useState know which state is "yours"?

Two identical useState('') calls — no key, no name. React matches state to call by order, storing hooks in a linked list on the fiber, walked in call order each render.

function useState(initial) {
  const fiber = currentFiber;
  const hook = fiber.hooks[hookIndex] ?? { state: initial, queue: [] };

  // drain queued updates from setState (the batch!)
  hook.queue.forEach(u => hook.state = typeof u === 'function' ? u(hook.state) : u);
  hook.queue = [];

  fiber.hooks[hookIndex] = hook;
  const i = hookIndex;
  const setState = (u) => { fiber.hooks[i].queue.push(u); scheduleRender(fiber); };

  hookIndex++;                       // advance for the NEXT hook call
  return [hook.state, setState];
}

Also note: setState closes over fiber + index, not the value — so it always reaches the latest state, and its identity is stable across renders (safe in dep arrays). useState is internally useReducer with a built-in reducer.

useRef = the deliberate escape

Effect timing: useLayoutEffect vs useEffect

• useEffect (default, 99%): after paint, non-blocking. Data fetching, subscriptions, logging.
• useLayoutEffect: before paint, sync. Only when you must read layout and re-mutate before the user sees it (measure → reposition a tooltip, sync scroll) to avoid a visible flicker. Costs: blocks paint, can force sync reflow (Part 2).

The dependency array decides whether an effect re-runs (shallow Object.is compare): [] = mount/unmount only; no array = every render. Cleanup runs before the next run and on unmount.

Re-render rules & memoization

A re-render = re-run your function + diff (cheap-ish). It is not a DOM update. Cost becomes real when the function does expensive work, the subtree is large, or a child genuinely commits DOM changes.

React 16 (2017) — "rebuild the foundation"

The Fiber rewrite. Headline features are all things the stack reconciler couldn't do:

React 18 (2022) — "turn on concurrency"

The machinery sat dormant since 16; createRoot switched it on. Each feature is a direct use of pausable + prioritizable rendering:

• useTransition / startTransition — mark an update low-priority; rendered in interruptible slices, preempted by urgent updates. (The lanes model exposed as API.)
• useDeferredValue — same idea, value-side.
• Automatic batching — now batches everywhere (Part 3), via the scheduler.
• Suspense for data + Streaming SSR — a component "suspends" (throws a promise); Fiber pauses that subtree, shows a fallback, resumes on resolve. renderToPipeableStream streams HTML in chunks with selective hydration.
• useId — hydration-safe stable IDs.
• useSyncExternalStore — lets external stores (Redux/Zustand) subscribe without tearing under concurrent rendering (a risk concurrency itself introduced).

React 19 (2024) — "product features on top of concurrency"

• Actions / useActionState / <form action> — async functions wired into transitions; pending state, errors, sequencing handled for you. (Under the hood: transitions.)
• use(promise) / use(context) — read a promise or context during render, integrates with Suspense; can be called conditionally (it's a primitive, not an index-slot hook).
• useOptimistic — built-in optimistic UI with auto-revert on failure.
• React Server Components + Server Actions — components that render server-only (zero client JS), direct backend access; 'use server' RPC-style calls. Changes where UI = f(state) runs.
• React Compiler ("Forget") — build-time auto-memoization, making manual memo/useMemo/useCallback largely unnecessary.
• Smaller wins — ref as a regular prop (no forwardRef), <Context> as provider, document metadata hoisting, resource preloading.

The whole arc on one page

One line per concept