Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 73 ยท Widgets and the widget tree

Widget, Element and RenderObject Trees

Learn how Flutter stays fast: the widget, element and render object trees, why widgets are cheap, how elements are reused by type and key, and how rebuilds work.

In the last lesson you saw that build returns a fresh tree of widgets, and that Flutter may call it many times per second. That raises a fair question: if we create a whole new description on every change, why is Flutter not slow? Throwing everything away and redrawing the screen from scratch would be wasteful.

The answer is that Flutter does not keep one tree, it keeps three. Widgets are cheap throwaway descriptions. A longer-lived layer of elements compares the new description with the old one. And the heavy objects that measure and paint, the render objects, are updated in place, only where something really changed. Understanding this makes rebuilds, keys and performance advice make sense. This lesson builds on Everything is a widget.

Real vs stand-in. The framework classes named here (Element, RenderObject, updateRenderObject) are real. This site cannot run Flutter, so the live examples are JavaScript stand-ins that implement the same reuse rule: reuse an element when the widget type (and key) matches, otherwise replace it.

Three trees, three jobs

Widgets Cheap, immutable descriptions.
Elements Long-lived links that hold state.
Render objects Measure, paint and hit-test.
1 / 2

The three trees

The widget tree is what your code writes: Center โ†’ Container โ†’ Text. Widgets are immutable and tiny, usually a few fields. They have no position and no size. They describe configuration only. Creating thousands per frame is fine, and discarding them costs almost nothing.

The element tree is the framework's own bookkeeping. For every place where a widget is mounted in the tree, there is one Element. The element remembers which widget currently configures it, who its parent and children are and, for a StatefulWidget, it owns the State object (StatefulWidget and setState). The BuildContext you receive in build is in fact that element. Elements are long-lived: they persist across rebuilds.

The render object tree does the actual work: it receives constraints from its parent, decides its size, positions its children, paints, and responds to touches. Not every widget has one. StatelessWidget and StatefulWidget are compositions, they just return other widgets. Only RenderObjectWidgets such as Padding, Text-related rendering widgets, Flex (the base of Row and Column) and Stack create RenderObjects. That is why the render tree is smaller than the widget tree.

flowchart LR
  W["Widget<br/>(configuration)"] -->|"createElement"| E["Element<br/>(instance in the tree)"]
  E -->|"createRenderObject"| R["RenderObject<br/>(layout and paint)"]
  W2["New widget"] -->|"update"| E
  E -->|"updateRenderObject"| R

A widget creates an element once; later widgets only update it, and the element updates the render object.

What happens on a rebuild

When a widget's build runs again, it returns new child widgets. For each child slot, the element runs one simple check against the child it already has:

  1. Is the old widget and the new widget the same runtimeType and the same key?
  2. If yes, keep the element and just give it the new widget. The element updates its render object with the new configuration (updateRenderObject) and continues into its children.
  3. If no, unmount the old element and its subtree, create a new element from the new widget, and build it from scratch.

Step 2 is why rebuilds are fast. If a Text('Score: 3') becomes Text('Score: 4'), the same element and render object stay, and only the string inside the render object changes. Layout and paint run just for what is marked dirty.

Step 3 is why changing the type at a position resets everything below: swapping a Column for a Row throws away the old subtree, including any State inside it. Keys, the second half of the check, are the topic of Keys and widget identity.

There is one more shortcut. If the new widget is identical (the very same instance) to the old one, Flutter skips the update completely. That is how const widgets help: a const Text('Hi') is created once at compile time, so the framework sees the same object and does not rebuild that subtree at all.

DART
Column(
  children: [
    Text('Score: $score'),            // new widget each build, element reused
    const SizedBox(height: 8),        // identical instance: skipped entirely
    const Icon(Icons.star),           // identical instance: skipped entirely
  ],
)

Stand-in: diffing a tree

Here is the reconciliation rule in about thirty lines. Each "element" records how many times it was created and updated, so you can see which parts survive.

JS Reuse an element when type matches

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In step 2 the ids stay #1 #2 #3: three elements, only updated. In step 3 the root type changed, so the whole subtree was replaced with #4 #5 #6.

Why this matters for state

State lives in the element tree. The next stand-in attaches a counter to each element and shows what happens to it when a position keeps its type versus when the type changes.

JS State survives only while the type matches

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Switching back does not resurrect the old counter: when the element was unmounted, its State was disposed. This is exactly the behavior you see when a widget at the same position in a Column is replaced by a different type.

Layout: render objects do the heavy lifting

After the element tree is updated, the render objects that were marked dirty run layout and paint. Layout follows a rule you will study in Constraints go down, sizes go up: a parent passes constraints to each child, the child picks a size within them, and the parent positions it. Flutter tries to make each render object's layout a single pass through the tree, which keeps layout linear in the number of dirty objects.

Two more facts help in practice:

  • Relayout boundaries stop a size change from propagating upward to the parent when the child's size cannot affect it (for example a widget with a tight fixed size).
  • Repaint boundaries (RepaintBoundary) let a frequently changing part, like an animation, repaint without repainting the rest of the screen. Many built-in scrollables add them for you.

You will use these ideas when profiling in Performance and DevTools.

Practical advice

  • Do not fear rebuilding. build is designed to be called often. Fear expensive work inside build.
  • Use const constructors so unchanged subtrees are skipped.
  • Split large widgets into smaller classes, so a state change rebuilds only the small part that needs it (you will see this in StatefulWidget and setState).
  • Do not change a widget's type at a position just to toggle visibility if you want to keep its state; prefer keeping the same type and changing properties, or give it a key.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which of the three trees holds the State object of a StatefulWidget?

    Elements are long-lived and own the State. Widgets are discarded and recreated; render objects only measure and paint.
  2. 2. A parent rebuilds and returns a Text widget where the old child was also a Text with the same key. What happens to the element?

    When runtimeType and key match, the element is kept and updated with the new configuration.
  3. 3. Why does a const widget make rebuilds cheaper?

    An identical (same instance) widget needs no update, so the framework skips it and everything below.
  4. 4. Which widgets create RenderObjects?

    StatelessWidget and StatefulWidget just compose other widgets. Render objects come from RenderObjectWidgets.

Summary

  • Flutter keeps three trees: cheap immutable widgets, long-lived elements, and render objects that lay out and paint.
  • On rebuild, an element is reused when the new widget has the same type and key; otherwise it and its subtree are replaced and state is lost.
  • Render objects are updated in place, and only dirty ones relayout and repaint.
  • Identical (const) widgets are skipped entirely.
  • BuildContext is the element, which is why it represents a position in the tree.

Next: StatefulWidget and setState