Hooks Under the Hood

How hooks are stored and how setState turns into a render. Read from renderWithHooks, mountWorkInProgressHook, updateWorkInProgressHook, mountState, dispatchSetStateInternal, updateReducerImpl, mountMemo, mountRef and pushSimpleEffect in the React 19.2.5 build, plus react.dev’s Rules of Hooks and Queueing a Series of State Updates. Part of React Internals. It builds on React Fiber (hooks live on the fiber). My own notes and clarifications are marked with > 💬.

Interview Q&A

How a hook call finds its data

useState from the react package is almost empty. It forwards to whatever dispatcher is currently installed:

// react package, simplified
export function useState(initialState) {
	return ReactSharedInternals.H.useState(initialState)
}

renderWithHooks (called from beginWork for function components) installs the right dispatcher, calls your component, and removes it again:

function renderWithHooks(current, workInProgress, Component, props) {
	currentlyRenderingFiber = workInProgress
	workInProgress.memoizedState = null     // hook list is rebuilt this render
	workInProgress.updateQueue = null       // effect list is rebuilt this render
	ReactSharedInternals.H =
		current === null || current.memoizedState === null
			? HooksDispatcherOnMount      // first render: useState → mountState
			: HooksDispatcherOnUpdate     // later renders: useState → updateReducer
	let children = Component(props)
	ReactSharedInternals.H = ContextOnlyDispatcher   // hooks called outside render now throw
	// … checks that the same number of hooks was called
	return children
}

ContextOnlyDispatcher is where the “Invalid hook call. Hooks can only be called inside of the body of a function component” error comes from. Outside a render, H points to a dispatcher whose hooks all throw.

The hook list

Each hook is one object (from mountWorkInProgressHook):

function mountWorkInProgressHook() {
	var hook = {
		memoizedState: null,   // this hook's value (meaning depends on the hook type)
		baseState: null,       // state before any skipped low-priority updates
		baseQueue: null,       // skipped updates, to replay later
		queue: null,           // pending updates (useState/useReducer)
		next: null             // the next hook
	}
	null === workInProgressHook
		? (currentlyRenderingFiber.memoizedState = workInProgressHook = hook)  // first hook
		: (workInProgressHook = workInProgressHook.next = hook)                // append
	return workInProgressHook
}

On updates, updateWorkInProgressHook walks two lists in lockstep: the current fiber’s hooks (currentHook) and the new work-in-progress hooks. It clones each current hook as it goes. If the current list runs out early, it throws:

if (null === nextCurrentHook) {
	throw Error("Rendered more hooks than during the previous render.")
}

What memoizedState holds, per hook type (from mountState, mountRef, mountMemo, mountEffectImpl):

areHookInputsEqual compares deps element by element with Object.is:

for (var i = 0; i < prevDeps.length && i < nextDeps.length; i++)
	if (!objectIs(nextDeps[i], prevDeps[i])) return false
return true

Why conditional hooks break, concretely

function Form({ showName }) {
	if (showName) {
		const [name, setName] = useState('Ada')   // hook #1 (only sometimes)
	}
	const [age, setAge] = useState(36)          // hook #1 or #2
	useEffect(() => { document.title = age })   // hook #2 or #3
}

react.dev’s rule: “Don’t call Hooks inside loops, conditions, nested functions, or try/catch/finally blocks.”

setState: from call to render

mountState creates the queue and the bound dispatcher:

function mountState(initialState) {
	const hook = mountStateImpl(initialState)   // memoizedState = initialState (or initializer())
	const queue = hook.queue
	const dispatch = dispatchSetState.bind(null, currentlyRenderingFiber, queue)
	queue.dispatch = dispatch
	return [hook.memoizedState, dispatch]
}

Calling dispatch(action) → dispatchSetState picks a lane (requestUpdateLane, see Scheduler, Lanes and Batching) → then dispatchSetStateInternal, simplified from the source:

function dispatchSetStateInternal(fiber, queue, action, lane) {
	const update = { lane, action, hasEagerState: false, eagerState: null, next: null }

	// EAGER BAILOUT: only if this fiber has no other pending updates
	if (fiber.lanes === 0 && (fiber.alternate === null || fiber.alternate.lanes === 0)) {
		const currentState = queue.lastRenderedState
		const eagerState = queue.lastRenderedReducer(currentState, action)  // run the update NOW
		update.hasEagerState = true
		update.eagerState = eagerState
		if (Object.is(eagerState, currentState)) {
			enqueueUpdate(fiber, queue, update, NoLane)   // keep it, but DON'T schedule a render
			return false
		}
	}

	const root = enqueueConcurrentHookUpdate(fiber, queue, update, lane)  // stash update, walk up to the root
	if (root !== null) scheduleUpdateOnFiber(root, fiber, lane)            // mark lanes, schedule root
	return true
}

Stashed updates are linked into queue.pending when the next render starts (finishQueueingConcurrentUpdates). The pending queue is a circular linked list. queue.pending points to the last update, and last.next is the first, so appending is O(1) and reading from the start is O(1).

Processing the queue during render

When the component renders again, the update dispatcher’s useState calls updateReducer(basicStateReducer). basicStateReducer is:

function basicStateReducer(state, action) {
	return typeof action === 'function' ? action(state) : action
}

updateReducerImpl moves queue.pending into the hook’s baseQueue, then loops over the updates:

newState = hook.baseState
for each update in baseQueue:
	if update.lane is NOT in the lanes being rendered:
		skip it: copy it into a new baseQueue (and keep newBaseState frozen at this point)
	else:
		newState = update.hasEagerState ? update.eagerState : reducer(newState, update.action)
hook.memoizedState = newState
if newState is not Object.is-equal to the old state: didReceiveUpdate = true

The “skip and keep” branch is what makes priorities safe. A sync render in the middle of a pending transition applies only the sync updates, but it keeps the transition updates and everything queued after them in baseQueue. When the transition renders, it replays them all in the original order from baseState. That’s why updater functions can run more than once, and why they must be pure.

Queue processing, step by step

const [count, setCount] = useState(0)

function handleClick() {
	setCount(count + 1)        // action: 1
	setCount((c) => c + 1)     // action: c => c + 1
	setCount(42)               // action: 42
	setCount((c) => c * 2)     // action: c => c * 2
}

In the render, updateReducer folds the queue:

One render, and count === 84. react.dev’s summary: React “waits until all code in the event handlers has run before processing your state updates.”

Rules and caveats

• Call hooks at the top level, in the same order, every render. The hook list is positional.
• Setters are stable, state values are snapshots. count inside a handler is the value from the render that created the handler. Use updater functions when the next state depends on the previous one.
• Setting equal state is (nearly) free. The eager Object.is check skips scheduling when possible. When it can’t run early, the render still bails out of children.
• Updater functions and reducers must be pure. They can be replayed when lanes are rebased, and Strict Mode calls them twice.
• useRef is just a hook whose memoizedState is a mutable object React never looks inside. Changing .current never schedules anything.
• Deps are compared with Object.is per element. A new object or array in deps means “changed” every render.

Sources

• React 19.2.5 source: renderWithHooks, mountWorkInProgressHook, updateWorkInProgressHook, mountState, dispatchSetState, dispatchSetStateInternal, basicStateReducer, updateReducerImpl, mountMemo, updateMemo, mountRef, mountEffectImpl, pushSimpleEffect, areHookInputsEqual
• React source: ReactFiberHooks.js
• react.dev: Rules of Hooks
• react.dev: Queueing a Series of State Updates

Primary source: github.com/facebook/react/blob/main/packages/react-reconciler/src/ReactFiberHooks.js