Inside Fiber: in-depth overview of the new reconciliation algorithm in React

The how and why on everything from React elements to Fiber nodes

React is a JavaScript library for building user interfaces. At its core lies the mechanism that tracks changes in a component state and projects the updated state to the screen. In React we know this process as reconciliation. We call the method and the framework checks if the state or props have changed and re-renders a component on UI.

React’s docs provide a good high-level overview of the mechanism: the role of React elements, lifecycle methods and the method, and the diffing algorithm applied to a component’s children. The tree of immutable React elements returned from the method is commonly known as the “virtual DOM”. That term helped explain React to people early on, but it also caused confusion and isn’t used in the React documentation anymore. In this article I’ll stick to calling it a tree of React elements.

Besides the tree of React elements, the framework has always had a tree of internal instances (components, DOM nodes etc.) used to keep the state. Starting from version 16, React rolled out a new implementation of that internal instances tree and the algorithm that manages it code-named Fiber. To learn about the advantages which the Fiber architecture brings check out The how and why on React’s usage of linked list in Fiber.

This article would take me a lot longer to write and would be less comprehensive without the help of Dan Abramov! 👍

This is the first article in the series aimed at teaching you internal architecture of React. In this article I want to provide an in-depth overview of important concepts and data structures relevant to the algorithm. Once we have enough background, we’ll explore the algorithm and main functions used to traverse and process the fiber tree. Next articles in the series will demonstrate how React uses the algorithm to perform initial render and process state and props updates. From there we’ll move on to the details of the scheduler, the child reconciliation process, and the mechanism of building an effects list.

Follow me to stay tuned!

I’m going to give you some pretty advanced knowledge here 🧙‍. I encourage you to read it to understand the magic behind the inner workings of Concurrent React. This series of articles will also serve you as a great guide if you plan to start contributing to React. I’m a strong believer in reverse-engineering, so there will be a lot of links to the sources from the recent version 16.6.0.

It’s definitely quite a lot to take in, so don’t feel stressed if you don’t understand something right away. It takes time as everything worthwhile. Note that you don’t need to know any of it to use React. This article is about how React works internally.

I work as a Developer Advocate at ag-Grid. If you’re curious to learn about data grids or looking for the ultimate React data grid solution, get in touch or give it a try with the guide “Get started with React grid in 5 minutes”. I’m happy to answer any questions you may have.

Setting the background

Here’s a simple application that I’ll use throughout the series. We have a button that simply increments a number rendered on the screen:

And here’s the implementation:

You can play with it here. As you can see, it’s a simple component that returns two child elements and from the method. As soon as you click on the button, the state of the component is updated inside the handler. This, in turn, results in the text update for the element.

There are various activities React performs during reconciliation. For example, here are the high-level operations React performs during the first render and after state update in our simple application:

  • updates property in the of
  • retrieves and compares children of and their props
  • updates props for the element

There are other activities performed during reconciliation like calling lifecycle methods or updating refs. All these activities are collectively referred to as “work” in the Fiber architecture. The type of work usually depends on the type of React element. For example, for a class component, React needs to create an instance, while it doesn’t do that for a functional component. As you know, we have many kinds of elements in React, e.g. class and functional components, host components (DOM nodes), portals etc. The type of React element is defined by the first parameter to the createElement function. This function is generally used in the method to create an element.

Before we begin our exploration of the activities and the main fiber algorithm, let’s first get ourselves familiar with the data structures used internally by React.

From React Elements to Fiber nodes

Every component in React has a UI representation we can call a view or a template that’s returned from the method. Here’s the template for our component:

React Elements

Once a template goes through the JSX compiler, you end up with a bunch of React elements. This is what’s really returned from the method of React components, not HTML. Since we’re not required to use JSX, the method for our component could be re-written like this:

The calls to in the method will create two data structures like this:

You can see that React adds the property to these objects to uniquely identify them as React elements. Then we have properties , and that describe the element. The values are taken from what you pass to the function. Notice how React represents text content as children of the and nodes. And how the click handler is part of the element props. There are other fields on React elements like the field that are beyond the scope of this article.

The React element for doesn’t have any props or a key:

Fiber nodes

During reconciliation data from every React element returned from the method is merged into the tree of fiber nodes. Every React element has a corresponding fiber node. Unlike React elements, fibers aren’t re-created on every render. These are mutable data structures that hold components state and DOM.

We discussed earlier that depending on the type of a React element the framework needs to perform different activities. In our sample application, for the class components it calls lifecycle methods and the method, whereas for the host component (DOM node) it performs DOM mutation. So each React element is converted into a Fiber node of corresponding type that describes the work that needs to be done.

You can think of a fiber as a data structure that represents some work to do or, in other words, a unit of work. Fiber’s architecture also provides a convenient way to track, schedule, pause and abort the work.

When a React element is converted into a fiber node for the first time, React uses the data from the element to create a fiber in the createFiberFromTypeAndProps function. In the consequent updates React reuses the fiber node and just updates the necessary properties using data from a corresponding React element. React may also need to move the node in the hierarchy based on the prop or delete it if the corresponding React element is no longer returned from the method.

Check out the ChildReconciler function to see the list of all activities and corresponding functions React performs for existing fiber nodes.

Because React creates a fiber for each React element and since we have a tree of those elements, we’re going to have a tree of fiber nodes. In the case of our sample application it looks like this:

All fiber nodes are connected through a linked list using the following properties on fiber nodes: , and . For more details on why it works this way, check out my article The how and why on React’s usage of linked list in Fiber if you haven’t read it already.

Current and work in progress trees

After the first render, React ends up with a fiber tree that reflects the state of the application that was used to render the UI. This tree is often referred to as current. When React starts working on updates it builds a so-called workInProgress tree that reflects the future state to be flushed to the screen.

All work is performed on fibers from the tree. As React goes through the tree, for each existing fiber node it creates an alternate node that constitutes the tree. This node is created using the data from React elements returned by the method. Once the updates are processed and all related work is completed, React will have an alternate tree ready to be flushed to the screen. Once this tree is rendered on the screen, it becomes the tree.

One of React’s core principles is consistency. React always updates the DOM in one go — it doesn’t show partial results. The tree serves as a “draft” that’s not visible to the user, so that React can process all components first, and then flush their changes to the screen.

In the sources you’ll see a lot of functions that take fiber nodes from both the and trees. Here’s the signature of one such function:

Each fiber node holds a reference to its counterpart from the other tree in the alternate field. A node from the tree points to the node from the tree and vice versa.


We can think of a component in React as a function that uses the state and props to compute the UI representation. Every other activity like mutating the DOM or calling lifecycle methods should be considered a side-effect or, simply, an effect. Effects are also mentioned in the docs:

You’ve likely performed data fetching, subscriptions, or manually changing the DOM from React components before. We call these operations “side effects” (or “effects” for short) because they can affect other components and can’t be done during rendering.

You can see how most state and props updates will lead to side-effects. And since applying effects is a type of work, a fiber node is a convenient mechanism to track effects in addition to updates. Each fiber node can have effects associated with it. They are encoded in the field.

So effects in Fiber basically define the work that needs to be done for instances after updates have been processed. For host components (DOM elements) the work consists of adding, updating or removing elements. For class components React may need to update refs and call the and lifecycle methods. There are also other effects corresponding to other types of fibers.

Effects list

React processes updates very quickly and to achieve that level of performance it employs a few interesting techniques. One of them is building a linear list of fiber nodes with effects for quick iteration. Iterating the linear list is much faster than a tree, and there’s no need to spend time on nodes without side-effects.

The goal of this list is to mark nodes that have DOM updates or other effects associated with them. This list is a subset of the tree and is linked using the property instead of the property used in the and trees.

Dan Abramov offered an analogy for an effects list. He likes to think of it as a Christmas tree, with “Christmas lights” binding all effectful nodes together. To visualize this, let’s imagine the following tree of fiber nodes where the highlighted nodes have some work to do. For example, our update caused to be inserted into the DOM, and to change attributes, and to fire a lifecycle method. The effect list will link them together so React can skip other nodes later:

You can see how the nodes with effects are linked together. When going over the nodes, React uses the pointer to figure out where the list starts. So the diagram above can be represented as a linear list like this:

As you can see, React applies effects in the order from children and up to parents.

Root of the fiber tree

Every React application has one or more DOM elements that act as containers. In our case it’s the element with the ID .

React creates a fiber root object for each of those containers. You can access it using the reference to the DOM element:

This fiber root is where React holds the reference to a fiber tree. It is stored in the property of the fiber root:

The fiber tree starts with a special type of fiber node which is . It’s created internally and acts as a parent for your topmost component. There’s a link from the fiber node back to the through the property:

You can explore the fiber tree by accessing the topmost fiber node through the fiber root. Or you can get an individual fiber node from a component instance like this:

Fiber node structure

Let’s now take a look at the structure of fiber nodes created for the component

and the DOM element:

There’s quite a lot of fields on fiber nodes. I’ve described the purpose of the fields , and in previous sections. Let’s now see why we need others.

stateNode Holds the reference to the class instance of a component, a DOM node or other React element type associated with the fiber node. In general, we can say that this property is used to hold the local state associated with a fiber.

type Defines the function or class associated with this fiber. For class components, it points to the constructor function and for DOM elements it specifies the HTML tag. I use this field quite often to understand what element a fiber node is related to.

tag Defines the type of the fiber. It’s used in the reconciliation algorithm to determine what work needs to be done. As mentioned earlier, the work varies depending on the type of React element. The function createFiberFromTypeAndProps maps a React element to the corresponding fiber node type. In our application, the property for the component is which denotes a and for the element it’s denoting a .

updateQueue A queue of state updates, callbacks and DOM updates.

memoizedState State of the fiber that was used to create the output. When processing updates it reflects the state that’s currently rendered on the screen.

memoizedProps Props of the fiber that were used to create the output during the previous render.

pendingProps Props that have been updated from new data in React elements and need to be applied to child components or DOM elements.

key Unique identifier with a group of children to help React figure out which items have changed, have been added or removed from the list. It’s related to the “lists and keys” functionality of React described here.

You can find the complete structure of a fiber node here. I’ve omitted a bunch of fields in the explanation above. Particularly, I skipped the pointers , and that make up a tree data structure which I described in my previous article. And a category of fields like , and that are specific to .

General algorithm

React performs work in two main phases: render and commit.

During the first phase React applies updates to components scheduled through or and figures out what needs to be updated in the UI. If it’s the initial render, React creates a new fiber node for each element returned from the method. In the following updates, fibers for existing React elements are re-used and updated. The result of the phase is a tree of fiber nodes marked with side-effects. The effects describe the work that needs to be done during the following phase. During this phase React takes a fiber tree marked with effects and applies them to instances. It goes over the list of effects and performs DOM updates and other changes visible to a user.

It’s important to understand that the work during the first phase can be performed asynchronously. React can process one or more fiber nodes depending on the available time, then stop to stash the work done and yield to some event. It then continues from where it left off. Sometimes though, it may need to discard the work done and start from the top again. These pauses are made possible by the fact that the work performed during this phase doesn’t lead to any user-visible changes, like DOM updates. In contrast, the following phase is always synchronous. This is because the work performed during this stage leads to changes visible to the user, e.g. DOM updates. That’s why React needs to do them in a single pass.

Calling lifecycle methods is one type of work performed by React. Some methods are called during the phase and others during the phase. Here’s the list of lifecycles called when working through the first phase:

  • [UNSAFE_]componentWillMount (deprecated)
  • [UNSAFE_]componentWillReceiveProps (deprecated)
  • getDerivedStateFromProps
  • shouldComponentUpdate
  • [UNSAFE_]componentWillUpdate (deprecated)
  • render

As you can see, some legacy lifecycle methods that are executed during the phase are marked as from the version 16.3. They are now called legacy lifecycles in the docs. They will be deprecated in future 16.x releases and their counterparts without the prefix will be removed in 17.0. You can read more about these changes and the suggested migration path here.

Are you curious about the reason for this?

Well, we’ve just learned that because the phase doesn’t produce side-effects like DOM updates, React can process updates asynchronously to components asynchronously (potentially even doing it in multiple threads). However, the lifecycles marked with have often been misunderstood and subtly misused. Developers tended to put the code with side-effects inside these methods which may cause problems with the new async rendering approach. Although only their counterparts without the prefix will be removed, they are still likely to cause issues in the upcoming Concurrent Mode (which you can opt out of).

Here’s the list of lifecycle methods executed during the second phase:

  • getSnapshotBeforeUpdate
  • componentDidMount
  • componentDidUpdate
  • componentWillUnmount

Because these methods execute in the synchronous phase, they may contain side effects and touch the DOM.

Okay, so now we have the background to take a look at generalized algorithm used to walk the tree and perform work. Let’s dive in.

Render phase

The reconciliation algorithm always starts from the topmost fiber node using the renderRoot function. However, React bails out of (skips) already processed fiber nodes until it finds the node with unfinished work. For example, if you call deep in the components tree, React will start from the top but quickly skip over the parents until it gets to the component that had its method called.

Main steps of the work loop

All fiber nodes are processed in the work loop. Here is the implementation of the synchronous part of the loop:

In the code above, the holds a reference to the fiber node from the tree that has some work to do. As React traverses the tree of Fibers, it uses this variable to know if there’s any other fiber node with unfinished work. After the current fiber is processed, the variable will either contain the reference to the next fiber node in a tree or . In that case React exits the work loop and is ready to commit the changes.

There are 4 main functions that are used to traverse the tree and initiate or complete the work:

To demonstrate how they are used, take a look at the following animation of traversing a fiber tree. I’ve used the simplified implementation of these functions for the demo. Each function takes a fiber node to process and as React goes down the tree you can see the currently active fiber node changes. You can clearly see on the video how the algorithm goes from one branch to the other. It first completes the work for children before moving to parents.

Note that straight vertical connections denote siblings, whereas bent connections denote children, e.g. doesn’t have children, while has one child .

Here’s the link to the video where you can pause the playback and inspect the current node and the state of functions. Conceptually, you can think of “begin” as “stepping into” a component, and “complete” as “stepping out” of it. You can also play with the example and the implementation here as I explain what these functions do.

Let’s start with the first two functions and :

The function receives a fiber node from the tree and starts the work by calling function. This is the function that will start all the activities that need to be performed for a fiber. For the purposes of this demonstration, we simply log the name of the fiber to denote that the work has been done. The function always returns a pointer to the next child to process in the loop or .

If there’s a next child, it will be assigned to the variable in the function. However, if there’s no child, React knows that it reached the end of the branch and so it can complete the current node. Once the node is completed, it’ll need to perform work for siblings and backtrack to the parent after that. This is done in the function:

You can see that the gist of the function is a big loop. React gets into this function when a node has no children. After completing the work for the current fiber, it checks if there’s a sibling. If found, React exits the function and returns the pointer to the sibling. It will be assigned to the variable and React will perform the work for the branch starting with this sibling. It’s important to understand that at this point React has only completed work for the preceding siblings. It hasn’t completed work for the parent node. Only once all branches starting with child nodes are completed does it complete the work for the parent node and backtracks.

As you can see from the implementation, both and are used mostly for iteration purposes, whereas the main activities take place in the and functions. In the following articles in the series we’ll learn what happens for the component and the node as React steps into and functions.

Commit phase

The phase begins with the function completeRoot. This is where React updates the DOM and calls pre and post mutation lifecycle methods.

When React gets to this phase, it has 2 trees and the effects list. The first tree represents the state currently rendered on the screen. Then there’s an alternate tree built during the phase. It’s called or in the sources and represents the state that needs to be reflected on the screen. This alternate tree is linked similarly to the current tree through the and pointers.

And then, there’s an effects list — a subset of nodes from the tree linked through the pointer. Remember that the effect list is the result of running the phase. The whole point of rendering was to determine which nodes need to be inserted, updated, or deleted, and which components need to have their lifecycle methods called. And that’s what the effect list tells us. And it’s exactly the set of nodes that’s iterated during the commit phase.

For debugging purposes, the tree can be accessed through the property of the fiber root. The tree can be accessed through the property of the node in the current tree.

The main function that runs during the commit phase is commitRoot. Basically, it does the following:

  • Calls the lifecycle method on nodes tagged with the effect
  • Calls the lifecycle method on nodes tagged with the effect
  • Performs all the DOM insertions, updates and deletions
  • Sets the tree as current
  • Calls lifecycle method on nodes tagged with the effect
  • Calls lifecycle method on nodes tagged with the effect

After calling the pre-mutation method , React commits all the side-effects within a tree. It does it in two passes. The first pass performs all DOM (host) insertions, updates, deletions and ref unmounts. Then React assigns the tree to the marking the tree as the tree. This is done after the first pass of the commit phase, so that the previous tree is still current during , but before the second pass, so that the finished work is current during . In the second pass React calls all other lifecycle methods and ref callbacks. These methods are executed as a separate pass so that all placements, updates, and deletions in the entire tree have already been invoked.

Here’s the gist of the function that runs the steps described above:

Each of those sub-functions implements a loop that iterates over the list of effects and checks the type of effects. When it finds the effect pertaining to the function’s purpose, it applies it.

Pre-mutation lifecycle methods

Here is, for example, the code that iterates over an effects tree and checks if a node has the effect:

For a class component, this effect means calling the lifecycle method.

DOM updates

commitAllHostEffects is the function where React performs DOM updates. The function basically defines the type of operation that needs to be done for a node and executes it:

It’s interesting that React calls the method as part of the deletion process in the function.

Post-mutation lifecycle methods

commitAllLifecycles is the function where React calls all remaining lifecycle methods and .

We’re finally done. Let me know what you think about the article or ask questions in the comments. Check out the next article in the series In-depth explanation of state and props update in React. I have many more articles in the works providing in-depth explanation for scheduler, children reconciliation process and how effects list is built. I also have plans to create a video where I’ll show how to debug the application using this article as a basis.

For more insights follow me on Twitter and on Medium. Thanks for reading! If you liked this article, hit that clap button below 👏. It means a lot to me and it helps other people see the story.

React Grid — the fastest and most feature-rich grid component from ag-Grid

React In Depth

The place where advanced React concepts are explained


5.7K claps
Max Koretskyi aka Wizard

Written by

I find patterns in frameworks and explain them. Angular & React contributor. Dev Evangelist at @ag_grid. Chief Inspiration Officer at @AngularInDepth. GDE, MVP.

React In Depth

The place where advanced React concepts are explained