Element Tree: what it is, relationship with RenderObject and working principle

What is Element Tree in Flutter?

Element Tree is an intermediate hierarchy in Flutter that is created based on the Widget Tree and manages the mounting of widgets into the application. Each element instance corresponds to one widget in the tree and stores a reference to it. The main difference between an element and a widget is that the element preserves its position in the tree between rebuilds, whereas the widget may be recreated on every build call.

Why Element Tree is needed

Without Element Tree, Flutter could not efficiently update the UI. If every rebuild recreated the RenderObject Tree, performance would be unacceptably low. Element Tree acts as a stabilizer: it retains references to RenderObject and State between updates, allowing Flutter to apply only minimal changes to the render tree.

Types of elements

Flutter uses three main types of elements: StatelessElement for StatelessWidget, StatefulElement for StatefulWidget, and LeafRenderObjectElement, SingleChildRenderObjectElement, MultiChildRenderObjectElement for RenderObjectWidget. Each type is specialized for its widget class and determines how the element interacts with RenderObject.

Relationship between Widget, Element and RenderObject in the three-layer architecture

The three-layer architecture of Flutter consists of Widget Tree (configuration), Element Tree (management), and RenderObject Tree (rendering). Element Tree is the connecting link: it reads configuration from Widget and passes commands to RenderObject. Without Element Tree, the framework could not efficiently synchronize the declarative description with the actual rendering.

How the element connects widget and RenderObject

When an element is mounted into the tree, it checks the widget type. If the widget is a RenderObjectWidget, the element creates the corresponding RenderObject and adds it to the RenderObject Tree. If the widget is a LeafRenderObjectWidget, the element creates a leaf RenderObject. For StatelessWidget and StatefulWidget, the element simply manages the mounting of child elements.

abstract class Element {
  Widget widget;
  Element? parent;
  List<Element>? children;

  void mount(Element? parent, dynamic newSlot);
  void update(Widget newWidget);
  void unmount();
}

This simplified code shows the basic structure of Element. Each element stores a reference to the current widget, parent element, and child elements. The mount, update, and unmount methods manage the lifecycle of the element and its associated RenderObject.

Element lifecycle: from creation to removal

Each element in Flutter goes through a sequence of lifecycle stages: creation, mounting, updating, and unmounting. Understanding these stages is necessary for debugging unexpected behavior, especially when working with animations, asynchronous operations, and state management.

Stage 1: Element creation

An element is created by calling the widget's createElement method. For StatelessWidget, a StatelessElement is created; for StatefulWidget, a StatefulElement is created (which also creates a State object). For RenderObjectWidget, the corresponding RenderObjectElement is created. Element creation occurs when the widget first appears in the Widget Tree.

Stage 2: Mounting

During mounting, the element is added to the Element Tree and receives a parent element. For RenderObjectElement, mounting also creates a RenderObject and inserts it into the RenderObject Tree. If the widget is a StatefulWidget, the State object's initState method is called at this stage.

Stage 3: Updating

When the widget rebuilds with a new configuration, the element receives the new widget through the update method. The element compares the type of the old and new widget: if the types match, the element updates its configuration; if not, the element is unmounted and a new one is created. This is called "widget change" and is the reason for state loss when changing types.

Stage 4: Unmounting

When a widget is removed from the Widget Tree, the element's unmount method is called. The element is removed from the Element Tree, the RenderObject is removed from the RenderObject Tree, and for StatefulWidget, the State object's dispose method is called. After unmount, the element can be reused if the widget appears again in the same position.

The role of keys in Element Tree

Keys are an element identification mechanism that allows Flutter to match widgets from the old and new Widget Tree not by position, but by a unique identifier. Keys are critically important when working with dynamic lists where the order of elements may change: adding, removing, or rearranging elements.

How keys affect Element Tree

Without a key, Flutter matches elements by their position in the tree: the element at position 0 from the old tree is replaced by the widget at position 0 from the new tree. If the order has changed, elements get mixed up, and state may be lost or bound to incorrect data. A key forces Flutter to search for an element by identifier rather than by position.

ValueKey, ObjectKey and UniqueKey

ValueKey uses a simple value (string, number) to identify an element. ObjectKey uses an object reference — suitable when the element has no stable string identifier. UniqueKey generates a unique identifier on each creation — used when each widget instance must be unique.

Column(
  children: items.map((item) => TodoItem(
    key: ValueKey(item.id),
    title: item.title,
    isDone: item.isDone,
  )).toList(),
)

In this example, ValueKey with item.id ensures that each TodoItem retains its state (e.g., input field focus) when the order of elements in the list changes. Without a key, the element at the first position would receive the state of the previous element at that same position.

How Element Tree manages state

State in Flutter is stored not in widgets, but in elements. When a StatefulWidget rebuilds and creates a new widget instance, the corresponding StatefulElement retains a reference to the old State object. The new widget is linked to the existing State, allowing data to be preserved between rebuilds.

Why state is not lost on rebuild

During a widget rebuild, Flutter creates a new instance of StatefulWidget, but the corresponding StatefulElement remains in the Element Tree. The element calls the update method on State, passing the new widget. Thus, the State object and its data are preserved. State loss only occurs when the widget type changes, the key changes, or the element is removed from the tree.

InheritedWidget and Element Tree

InheritedElement is a special element that allows child elements to receive data from a parent InheritedWidget without explicit passing through constructors. When InheritedWidget changes, InheritedElement notifies all dependent elements, which then rebuild. This mechanism underlies Theme, MediaQuery, and Provider.

• Dependency — an element registers as dependent on InheritedElement when calling dependOnInheritedWidgetOfExactType.
• Notification — when InheritedWidget changes, the framework marks all dependent elements as needing rebuild.
• Rebuild — dependent elements rebuild in the next frame, updating the UI according to the new data.

Impact of Element Tree on performance

Element Tree consumes memory and affects first render speed. Each element occupies a certain amount of memory: a reference to the widget, a reference to the parent, a list of child elements, a slot, and additional fields for RenderObjectElement. Optimizing Element Tree reduces startup time and decreases memory consumption.

Element reuse

Flutter tries to reuse elements during rebuild. If the widget in the new configuration has the same type and key, the element is not recreated — it is updated. This is significantly faster than creating a new element with subsequent mounting. However, when the type or key changes, the old element is unmounted and a new one is created from scratch.

RepaintBoundary and Element Tree

RepaintBoundary creates a separate RenderRepaintBoundary in the RenderObject Tree that isolates part of the tree. At the Element Tree level, RepaintBoundary does not create a special element — it uses SingleChildRenderObjectElement. The difference appears at the RenderObject level: when RepaintBoundary content changes, only the isolated area is repainted.

As the table shows, RepaintBoundary significantly reduces repaint time by isolating the changing area. At the Element Tree level, this requires no additional configuration — simply wrap the changing widget in RepaintBoundary.