Scheduler, Lanes and Batching

How React decides when to render and how urgently. It covers update priorities (lanes), batching, time slicing, interruption and starvation. Read from the React 19.2.5 build (requestUpdateLane, getEventPriority, getHighestPriorityLanes, ensureRootIsScheduled, performWorkOnRoot, scheduleTaskForRootDuringMicrotask) and the scheduler package (scheduler.development.js). Part of React Internals. This is the machinery behind Concurrent Rendering and useTransition and Avoiding Loading Flicker. My own notes and clarifications are marked with > 💬.

Interview Q&A

The problem: not all updates are equally urgent

A keystroke must show up within a frame. A search-results list for that keystroke can lag a bit. A prefetched offscreen tab can wait indefinitely. A single “render queue” can’t express that. React needs to:

1. label each update with a priority,
2. group updates of the same priority into one render (batching),
3. pick the most urgent group next,
4. yield during low-priority renders so urgent ones can cut in,
5. and not starve low-priority work forever.

Lanes handle 1–3 and 5. The Scheduler package handles 4.

Lanes: priority as bits

Selected lanes from the 19.2.5 build (lower bit = higher priority):

Because they’re bits:

const pending = SyncLane | TransitionLane1          // two kinds of work pending
(pending & SyncLane) !== 0                          // "is sync work pending?" → true
pending & -pending                                  // lowest set bit → SyncLane (most urgent)
fiber.childLanes |= lane                            // "something below me has this work"

getHighestPriorityLanes does exactly lanes & -lanes (two’s complement isolates the lowest set bit), except that all transition bits are returned together so they render as one batch.

How an update picks its lane

From requestUpdateLane(fiber):

function requestUpdateLane(fiber) {
	if (isRendering && workInProgressRootRenderLanes !== 0)
		return pickArbitraryLane(workInProgressRootRenderLanes)  // setState during render
	const transition = ReactSharedInternals.T
	if (transition !== null) return requestTransitionLane()      // inside startTransition
	return resolveUpdatePriority()                                // from the current event
}

function resolveUpdatePriority() {
	const updatePriority = ReactDOMSharedInternals.p   // set by flushSync etc.
	if (updatePriority !== 0) return updatePriority
	const event = window.event
	return event === undefined ? DefaultEventPriority : getEventPriority(event.type)
}

getEventPriority is a big switch over DOM event names: click, keydown, input, focusin and similar → DiscreteEventPriority (= SyncLane). mousemove, scroll, wheel, pointermove and similar → ContinuousEventPriority (= InputContinuousLane). Everything else → DefaultEventPriority (= DefaultLane).

This is why the same setState call gets different priorities depending on where it runs. In an onClick it’s SyncLane. In a setTimeout it’s DefaultLane. Inside startTransition it’s a transition lane, whatever the event.

Batching: queue now, render later

setState never renders by itself. The sequence is:

1. dispatchSetState creates an update { lane, action, next } and stashes it in a module-level concurrentQueues array, together with its fiber and hook queue (Hooks Under the Hood). getRootForUpdatedFiber walks return pointers up to find the root.
2. Later, when the next render starts (prepareFreshStack → finishQueueingConcurrentUpdates), each stashed update is linked into its hook’s circular queue, and markUpdateLaneFromFiberToRoot ORs the lane into fiber.lanes and into childLanes of every ancestor. The Work Loop uses that trail to find the changed fiber.
3. Right away, scheduleUpdateOnFiber → markRootUpdated (adds the lane to root.pendingLanes) → ensureRootIsScheduled(root) adds the root to a list and, if not already done, schedules a microtask (queueMicrotask).
4. The rest of your handler runs. More setState calls repeat 1–3 and find the microtask already scheduled.
5. In the microtask, processRootScheduleInMicrotask looks at each root’s pending lanes. Sync lanes are rendered right there, at the end of the microtask. Other lanes get a Scheduler task at a matching priority (continuous → UserBlockingPriority, default → NormalPriority, transitions → NormalPriority, idle → IdlePriority).

function handleClick() {
	setCount((c) => c + 1)   // queue update 1 (SyncLane), schedule microtask
	setFlag(true)            // queue update 2 (SyncLane), microtask already scheduled
	setText('hi')            // queue update 3
}                            // handler returns → microtask → ONE render with all 3

Before React 18, batching only happened inside React’s own event handlers, because it relied on a “we’re in a batch” flag that React set around its handlers. Updates in setTimeout or .then rendered once per setState. The microtask-based scheduling in 18+ batches everything that happens in the same tick. flushSync is the opt-out.

Sync vs concurrent: which loop runs

When the root’s task runs, performWorkOnRoot(root, lanes, forceSync) chooses the loop:

const shouldTimeSlice =
	!forceSync &&
	(lanes & 127) === 0 &&               // no Sync / InputContinuous / Default lanes (the "blocking" ones)
	(lanes & root.expiredLanes) === 0 || // and nothing has expired
	checkIfRootIsPrerendering(root, lanes)
shouldTimeSlice ? renderRootConcurrent(root, lanes) : renderRootSync(root, lanes, true)

The Scheduler package: time slicing

scheduler is a small standalone package that React uses as a cooperative task queue for the main thread.

A min-heap of tasks. scheduleCallback(priority, callback) creates a task with expirationTime = startTime + timeout, where the timeout depends on the priority (from the source):

Tasks are pushed onto a binary min-heap (push/siftUp/pop) keyed by sortIndex = expirationTime, so the most urgent task is always at the root of the heap, found in O(1) and removed in O(log n). Delayed tasks wait in a separate timerQueue heap, keyed by start time.

Running tasks in slices. The Scheduler’s host loop (performWorkUntilDeadline) pops tasks and runs them until shouldYieldToHost() says to stop:

function shouldYieldToHost() {
	// (simplified) keep going only while the current slice is under frameInterval
	return getCurrentTime() - startTime >= frameInterval   // frameInterval = 5 (ms)
}

If work remains, the Scheduler posts itself a new macrotask through a MessageChannel (setImmediate in Node, and setTimeout as a last resort). Between those macrotasks the browser can paint and dispatch input events.

Continuations. A task callback can return a function, which means “not done, call me again”. React’s concurrent render uses that. When workLoopConcurrentByScheduler exits because shouldYield() returned true, React’s task returns a continuation, and the next slice resumes at the remembered workInProgress fiber.

Interruption and restart

Say a transition render for a big list is halfway done and the user types a character:

1. The keydown handler calls setQuery, which gets SyncLane. The root now has SyncLane | TransitionLane1 pending.
2. The current slice ends (shouldYield). The microtask runs, sees a sync lane, and renders the root for SyncLane.
3. Since the new lanes differ from the in-progress ones, React calls prepareFreshStack, which throws away the half-built work-in-progress tree. Nothing was committed, so there’s nothing to undo.
4. The sync render and commit run. The input updates.
5. The transition lane is still pending. It’s rescheduled and starts over from the root, now with the newer state.

This is why transitions stay responsive and why their renders must be pure: they can run many times before one of them commits.

Starvation protection

In scheduleTaskForRootDuringMicrotask, React walks every pending lane bit. A lane that doesn’t have an expiration time yet gets one (computeExpirationTime: current time + 250ms for sync and continuous lanes, + 5000ms for default, transition and retry lanes; idle and offscreen never expire). A lane whose time has passed is added to root.expiredLanes:

expirationTime <= currentTime && (root.expiredLanes |= lane)

As shown above, any expired lane forces renderRootSync. A transition that has been interrupted for 5 seconds finishes without yielding.

Scheduling, step by step

A search box whose results update inside startTransition:

function Search() {
	const [text, setText] = useState('')
	const [query, setQuery] = useState('')
	const [isPending, startTransition] = useTransition()
	return (
		<>
			<input
				value={text}
				onChange={(e) => {
					setText(e.target.value)                        // urgent
					startTransition(() => setQuery(e.target.value)) // non-urgent
				}}
			/>
			<SlowResults query={query} dim={isPending} />
		</>
	)
}

The "a" results were never committed. The user saw every keystroke immediately.

Rules and caveats

• The default is synchronous. Clicks and typing render in one blocking pass. Use startTransition/useDeferredValue to make specific renders interruptible.
• Transitions must be pure and restartable. They can be thrown away and re-run any number of times.
• Batching is per tick. Updates separated by an await are in different ticks, and therefore separate renders.
• flushSync breaks batching on purpose. It renders and commits immediately at SyncLane. Use it sparingly (flushSync).
• Time slicing doesn’t make work cheaper. A 300ms render in a transition still costs 300ms of CPU. It just stops blocking input. Fix slow renders first (Optimize Rendering).
• Lane numbers are internal and change between versions (React 19 added a gesture lane, for example). Think in categories (sync, continuous, default, transition, idle), not values.

Sources

• React 19.2.5 source: requestUpdateLane, resolveUpdatePriority, getEventPriority, getHighestPriorityLanes, computeExpirationTime, ensureRootIsScheduled, processRootScheduleInMicrotask, scheduleTaskForRootDuringMicrotask, performWorkOnRoot, prepareFreshStack
• scheduler package source: unstable_scheduleCallback, push/pop (min-heap), shouldYieldToHost, frameInterval = 5, MessageChannel host loop
• React source: ReactFiberLane.js
• React 18 release post: automatic batching, concurrent React
• react.dev: useTransition

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