React's Current & Work-in-Progress Trees

Why it exists

Before React 16, large component tree updates could block the main thread, freezing the UI and creating a poor user experience. The two-tree architecture was introduced with the Fiber reconciler to enable concurrent rendering, allowing React to work on updates in chunks and yield to the browser to handle higher-priority tasks like user input.

The mental model

Think of double-buffering in graphics or a stage crew setting up the next scene behind a closed curtain. The current tree is the scene the audience is watching (what's rendered on screen). The workInProgress tree is the new scene being built in the background. React can assemble this new scene piece by piece. Once the new scene is fully prepared, the 'curtain' swaps instantly, and the workInProgress scene becomes the new current scene.

How it works

On an initial render, React creates a tree of 'fiber nodes' that represents the UI state; this is the current tree. When an update is triggered (e.g., by setState), React does not mutate the current tree. Instead, it creates a clone of it called the workInProgress tree. The reconciliation algorithm then walks this workInProgress tree, computing the differences and scheduling side-effects. This work can be split into chunks and paused. After the entire workInProgress tree is processed, React enters the synchronous 'commit phase'. It applies the DOM updates and then atomically points the current pointer to the finished workInProgress tree, making it the new current tree for the next render cycle.

When to use it

This is an internal React mechanism, not a pattern you implement yourself. You automatically benefit from it in React 16+ whenever a component re-renders. Understanding it is key to grasping how concurrent features like useTransition work and for debugging complex performance issues.

When not to use it

You cannot opt out of this behavior. However, knowing its limitations is useful. While the reconciliation 'render phase' is async and pausable, the 'commit phase' (when DOM mutations happen) is synchronous. If the final DOM manipulation itself is very heavy, it can still cause jank, even with concurrent rendering.

One canonical example

In a simple counter app, the initial render creates a current tree with a button and a span showing '0'. When you click the button, React creates a workInProgress copy. It traverses this copy, finds the span, and marks it for a text update to '1'. Once the traversal is complete, React commits the change, updating the real DOM and swapping the workInProgress tree to become the new current tree.