React Fiber

Notes from Andrew Clark’s React Fiber Architecture, Lin Clark’s talk A Cartoon Intro to Fiber, and the FiberNode / createWorkInProgress code in the React 19.2.5 source. Part of React Internals. How React walks these fibers is covered in The Work Loop. My own notes and clarifications are marked with > 💬.

Interview Q&A

The problem: a call stack can’t be paused

Before Fiber, rendering looked roughly like this:

function reconcile(element) {
	const children = render(element)   // call the component
	children.forEach(reconcile)          // recurse
}

The state of “where are we in the tree” lived on the JavaScript call stack. That has three consequences:

• It can’t be interrupted. To yield to the browser you’d have to return from every frame, losing your place.
• It can’t be prioritized. A keystroke arriving mid-render waits for the whole tree.
• It can’t be thrown away cleanly if the result is already stale.

Andrew Clark: “a fiber represents a unit of work”. A fiber is a virtual stack frame. The architecture doc: “The advantage of reimplementing the stack is that you can keep stack frames in memory and execute them however (and whenever) you want.” Because the “stack” is now heap objects, React’s loop can stop after any fiber, remember workInProgress (a single pointer), let the browser paint, and pick up exactly there.

What a fiber holds

The constructor from the 19.2.5 build, with profiler and dev-only fields removed:

function FiberNode(tag, pendingProps, key, mode) {
	this.tag = tag                  // what kind of fiber: FunctionComponent, HostComponent, …
	this.key = key
	this.elementType = null         // the element's type as written (e.g. the memo wrapper)
	this.type = null                // the resolved function/class, or 'div'
	this.stateNode = null           // DOM node for host fibers, class instance, or FiberRoot

	this.return = null              // parent
	this.child = null               // first child
	this.sibling = null             // next sibling
	this.index = 0                  // position among siblings (used by the list diff)

	this.ref = null
	this.pendingProps = pendingProps  // props for this render
	this.memoizedProps = null         // props used in the last completed render
	this.updateQueue = null           // effects list / class updates
	this.memoizedState = null         // function components: the first hook of the hooks list
	this.dependencies = null          // contexts this fiber reads

	this.mode = mode                  // ConcurrentMode, StrictMode bits
	this.flags = 0                    // side effects on this fiber (Placement, Update, …)
	this.subtreeFlags = 0             // OR of all flags below
	this.deletions = null             // children to delete in the commit

	this.lanes = 0                    // pending update priorities on THIS fiber
	this.childLanes = 0               // pending update priorities somewhere BELOW

	this.alternate = null             // the other version (current ↔ workInProgress)
}

Grouped by purpose:

Some common tag values: 0 FunctionComponent, 1 ClassComponent, 3 HostRoot, 5 HostComponent (div), 6 HostText, 7 Fragment, 11 ForwardRef, 14 MemoComponent, 15 SimpleMemoComponent, 13 SuspenseComponent.

Fibers are the “instances” of function components. A function component has no this. Its state lives on its fiber, in memoizedState. That’s why state survives exactly as long as the fiber does, and why Reconciliation decisions (“reuse this fiber or not”) decide whether state survives.

The tree is a linked list

A fiber doesn’t hold an array of children. It points to its first child, each child points to its next sibling, and every fiber points to its parent through return (named after the return address of a stack frame):

<App>
	<Header />
	<main>
		<Counter />
		<p>hi</p>
	</main>
</App>

This shape is what lets the work loop do a depth-first traversal with a while loop and one pointer instead of recursion.

Double buffering: current and work-in-progress

A fiber tree is never edited while it’s on screen. React keeps two trees:

• current: root.current, what the DOM reflects right now.
• workInProgress: the tree being rendered.

Each fiber in one tree points to its counterpart in the other through alternate. When React starts on a fiber it calls createWorkInProgress(current, pendingProps), from the source:

function createWorkInProgress(current, pendingProps) {
	var workInProgress = current.alternate
	null === workInProgress
		? ((workInProgress = createFiber(current.tag, pendingProps, current.key, current.mode)),
			(workInProgress.elementType = current.elementType),
			(workInProgress.type = current.type),
			(workInProgress.stateNode = current.stateNode),
			(workInProgress.alternate = current),
			(current.alternate = workInProgress))
		: ((workInProgress.pendingProps = pendingProps),
			(workInProgress.type = current.type),
			(workInProgress.flags = 0),
			(workInProgress.subtreeFlags = 0),
			(workInProgress.deletions = null))
	// … then copy lanes, child, memoizedProps, memoizedState, updateQueue, sibling, index, ref
	return workInProgress
}

So after the first update, React recycles the fiber from two renders ago instead of allocating a new one. When the render completes, the commit does root.current = finishedWork, and the trees swap roles:

Why this matters for you:

• Interruptible rendering is safe. Abandoning a render just drops the work-in-progress pointers. The current tree was never touched.
• State reads are consistent. A render reads from the work-in-progress hooks, which start as copies of current’s. Nothing leaks to the screen until commit.
• “Tearing” is only possible with outside stores. React’s own state is snapshotted per render. External mutable stores need useSyncExternalStore (useSyncExternalStore) to stay consistent across a render that yields.

Fiber, step by step

What exists at each moment for a Counter whose button is clicked:

Rules and caveats

• Fibers are internal. Never rely on fields like _reactInternals or __reactFiber$… on DOM nodes. They’re for DevTools and change between versions.
• One fiber = one mounted instance. Rendering the same component in two places makes two fibers with independent state.
• Unmounted means the fiber is gone. Its hooks, and therefore its state, are garbage.
• “Fiber” doesn’t mean faster by default. It makes scheduling possible. Most updates (clicks, typing) still render synchronously. Only transitions and deferred values are time-sliced. See Scheduler, Lanes and Batching.

Sources

• Andrew Clark: React Fiber Architecture
• Lin Clark: A Cartoon Intro to Fiber (React Conf 2017)
• React 19.2.5 source: FiberNode, createFiber, createWorkInProgress, and root.current = finishedWork in flushMutationEffects

Primary source: github.com/acdlite/react-fiber-architecture