Config / instance / pixels. See Part 1.

Widget = immutable config (recreated each build); Element = persistent instance (holds state, is the BuildContext, reconciles); RenderObject = layout + paint.

Not the widget.

In the State held by the StatefulElement (Element tree). That's why state survives widget rebuilds.

Elements/render objects persist.

Widgets are cheap immutable config (often const, canonicalized); the expensive Elements and RenderObjects are kept and updated in place via reconciliation, so only changed properties are touched.

Two fields.

An Element is reused for a new widget only if runtimeType and key both match. Match → update in place (state kept); mismatch → dispose + rebuild (state lost).

runtimeType.

Replaced — different runtimeType, so canUpdate is false; the old Element is disposed.

Same type, diff key.

Replaced — same type but different key fails canUpdate; state is lost.

null/null/canUpdate/else.

New widget null → deactivate old child. Old child null → inflate/mount new. canUpdate true → reuse (child.update). canUpdate false → replace (deactivate old, inflate new).

Compose vs render.

ComponentElement (composes other widgets, e.g. StatelessElement/StatefulElement) and RenderObjectElement (creates/manages a RenderObject).

Dirty list.

It tracks dirty elements (from markNeedsBuild) and each frame rebuilds them in tree order (buildScope), running build/updateChild to reconcile, after which changed render objects lay out and paint.

markNeedsBuild → BuildOwner → canUpdate → render.

Mutate fields → markNeedsBuild() on the Element → BuildOwner dirty list → next frame build() + updateChild/canUpdate reconcile → changed RenderObjects markNeedsPaint/Layout → pipeline paints.

Reused element → update.

canUpdate matches (same type+key), so the Element is reused and updateRenderObject mutates the existing render object's text + marks needs-paint. New render objects only appear on element replacement.

Middle.

The Element — Element implements BuildContext.

Disposable vs persistent.

So widgets can be recreated cheaply every build while a persistent Element holds state and decides what actually changed — keeping expensive render objects alive across rebuilds.

Identical → skip.

A const widget is canonicalized to one instance; on rebuild the new child is identical() to the old, so canUpdate reuses the Element and Flutter can skip that subtree entirely. (const)

State Mgmt Part 1.

setState calls markNeedsBuild() on the State's Element, enrolling it in the BuildOwner's dirty list so it rebuilds next frame. It's the bridge from a field change to reconciliation. (State Mgmt Part 1)

canUpdate true.

Reused — same type+key, so the Element/render object are kept and just updated to show 'b'.

Position-paired (+keys).

Children are matched by position (with keys helping match by identity within a list), so each old/new child pair is compared once via canUpdate — a single linear walk, not all-pairs matching.

The key half of canUpdate.

The key in canUpdate — it makes reconciliation match an Element by identity instead of position, deciding which Element/state is reused.

No.

No — only same-type, stateful widgets in a collection that can reorder or change membership generally need them.

Matched by slot.

Without keys, widgets match existing Elements by position, so State stays glued to the slot. After a reorder/removal the wrong rows keep state. Keys make matching follow item identity.

Value.

ValueKey(item.id).

Object.

ObjectKey(item).

Unique.

UniqueKey() — a new identity each build forces a fresh Element. Risk: in a list it destroys reuse and resets all state every frame.

Siblings vs app.

LocalKey is unique among siblings; GlobalKey is unique across the whole app (and grants state/context access + re-parenting).

GlobalKey currentState.

final k = GlobalKey<FormState>();
Form(key: k, ...);
k.currentState!.validate();

Re-parent the element.

It identifies an Element globally, so when the keyed widget reappears elsewhere, Flutter re-parents the existing Element (with its State/RenderObject) instead of rebuilding — preserving state.

Global registry.

The framework maintains a global registry mapping each GlobalKey to its Element (for lookups/re-parenting), and it must stay unique app-wide — more bookkeeping than a sibling-scoped LocalKey.

Sibling level.

On the item widget that's a direct child of the collection's children (the sibling level the list reconciles) — not buried deeper inside the item.

Stable / stateless / distinct types.

When the structure is stable and never reorders, the widgets are stateless, or siblings are different types (so runtimeType already distinguishes them).

Keys make them follow.

Add distinct keys (ValueKey('a'), ValueKey('b')). Without them both are TextField at positions 0/1, so swapping reuses Elements by slot. Keys make Flutter match by identity so the fields truly swap.

Value/Object/Unique.

ValueKey, ObjectKey, UniqueKey.

New identity each build.

Every build yields new keys → canUpdate always fails → every item's Element/state rebuilt from scratch each frame, destroying reuse and resetting state.

Mostly harmless.

Functionally it's harmless (and can aid diffing), but it's unnecessary — with stable order and no state there's nothing for keys to fix.

Must be unique.

It throws — a GlobalKey must identify one Element at a time. Duplicate simultaneous use violates uniqueness and crashes.

The element.

The Element for a widget — a handle to its location in the Element tree.

Up.

Upward from context to the nearest matching ancestor (usually an InheritedWidget).

Builder.

Wrap the child in a Builder so its context is below the Scaffold:

Scaffold(body: Builder(builder: (context) =>
  ...ScaffoldMessenger.of(context)...));

Above it.

The page's context sits above the Scaffold, and of searches upward — it can't find a Scaffold that's below the starting context.

mounted.

await something();
if (!context.mounted) return;
Navigator.of(context).pop();

Still in tree?

Whether the Element backing the context is still mounted in the tree. Check it after async gaps before using the context.

Doesn't react.

The dependency isn't set up to react to later changes and some lookups aren't valid that early; the value can go stale. Use didChangeDependencies or build.

Builder.

Builder — its builder callback receives a context below the Builder.

Different start points.

Theme.of searches upward from each context; if they start at different locations (one below an inner Theme override), their nearest Theme ancestor differs.

May deactivate.

A context is valid only while its Element is mounted/in place; after rebuilds/navigation/disposal it can be deactivated, so using a stored one throws "deactivated widget's ancestor." Capture concrete values synchronously instead.

State vs bare context.

In a State, use mounted (State.mounted). With a bare BuildContext (stateless callback), use context.mounted. Both mean "element still in the tree."

Lookups + anchor.

Find ancestors (of(context), inherited dependencies) and act as the anchor for Navigator/Theme/MediaQuery/overlays — all relative to its tree location.

Start node + register.

The context (Element) is the starting node for the upward type lookup and the node registered as a dependent, so the framework knows which element to rebuild when the inherited widget changes. (State Mgmt Part 2)

use_build_context...

use_build_context_synchronously.

No (directly).

Not directly via of-style lookups — those go upward. (You can reach a render object via findRenderObject, but normal inherited lookups only see ancestors.)

Location + upward.

A context is a location in the tree and lookups search upward from it; using a context from the wrong location (too high, deactivated, or another subtree) makes lookups fail or find the wrong ancestor.

Start/end.

initState (start) and dispose (end). didChangeDependencies is once-then-on-change; build/didUpdateWidget fire many times.

Birth → prep → deps → perform.

createState → initState → didChangeDependencies → build.

One-time setup.

One-time setup — create controllers/subscriptions, initial values. Call super.initState() first; don't do change-tracking inherited lookups or setState here.

Inherited vs own props.

didChangeDependencies when an inherited dependency (via of(context)) changes; didUpdateWidget(old) when the parent rebuilds with new widget config (same State reused).

didUpdateWidget.

@override
void didUpdateWidget(W old) {
  super.didUpdateWidget(old);
  if (old.stream != widget.stream) { _sub.cancel(); _sub = widget.stream.listen(_on); }
}

Same State reused.

canUpdate keeps the same State and just hands it a new widget — the Element isn't recreated, so initState doesn't run again. Reconcile prop-dependent setup in didUpdateWidget.

First / last.

super.initState() first, super.dispose() last.

Release resources.

Release everything acquired in setup — dispose() controllers, cancel() subscriptions/timers, remove listeners — to avoid leaks. super.dispose() last.

Reachable State.

Undisposed controllers/subscriptions keep the State (and its subtree) reachable, so the GC can't reclaim it — a retained-reference leak. (GC)

didChangeDependencies.

In didChangeDependencies — it re-runs when the inherited Locale changes.

Might return.

deactivate = removed from the tree but might be reinserted (e.g. GlobalKey re-parent). dispose = gone for good; release resources. deactivate is rarely overridden.

Just build.

No — only build. The lifecycle hooks belong to State.

false → guard async.

mounted is false. Async callbacks must check it before setState/using context, or they throw "setState after dispose."

initState + didUpdateWidget + dispose.

void initState() { super.initState(); _sub = stream(widget.symbol).listen(_on); }
void didUpdateWidget(o) { super.didUpdateWidget(o);
  if (o.symbol != widget.symbol) { _sub.cancel(); _sub = stream(widget.symbol).listen(_on); } }
void dispose() { _sub.cancel(); super.dispose(); }

reassemble.

reassemble() — dev-only (hot reload); never in production.

Runs often, unpredictably.

It can run many times per second (rebuilds, dependency changes) and must be safe to re-run. Side-effects (starting requests, mutating external state, creating controllers) there cause duplication, leaks, and bugs — those belong in initState/didUpdateWidget/callbacks.

deps vs widget.

Inherited value (read via of(context)) changed → didChangeDependencies. Your own widget.* props changed (parent rebuild) → didUpdateWidget. They're commonly confused; the source of the change tells you the hook.

Scrollable segment.

A scrollable segment of a viewport laid out with a scroll-aware protocol — a piece of the "belt" that a CustomScrollView arranges with others. (Part 5)

Many slivers.

ListView is a viewport with one sliver; CustomScrollView places multiple slivers in one viewport so they scroll together.

SliverConstraints → SliverGeometry.

Boxes: BoxConstraints → Size (2D). Slivers: SliverConstraints → SliverGeometry (1D, scroll-aware — scroll extent, paintExtent/visible amount, where the next sliver starts).

Adapter.

SliverToBoxAdapter(child: Card(...)).

Builder delegate.

SliverList(delegate: SliverChildBuilderDelegate(
  (c, i) => Tile(data[i]), childCount: data.length));

Lazy build.

SliverChildBuilderDelegate builds children lazily (only visible ones + a small cache) and disposes off-screen ones, keeping live Elements/RenderObjects roughly constant.

paintExtent shrinks.

As scrollOffset grows, its paintExtent (visible size) shrinks from expandedHeight toward the toolbar height. pinned clamps paintExtent at the toolbar height; floating lets it grow again on upward scroll.

SliverPadding.

SliverPadding — Padding is a box widget and can't sit in slivers: or wrap a sliver.

Stays at top.

Keeps the toolbar visible (pinned) at the top when scrolled, instead of scrolling fully away.

Unbounded + uncoordinated.

It causes unbounded-height errors, conflicting physics, and double scrollbars, and the regions don't coordinate. Use one CustomScrollView with multiple slivers instead.

FillRemaining.

SliverFillRemaining(child: Footer()).

Visible vs total.

scrollExtent = the sliver's total length along the scroll axis; paintExtent = how much of it is currently visible in the viewport.

AppBar/List/Grid.

SliverAppBar (collapsing header), SliverList (lazy list), SliverGrid (lazy grid). Also SliverToBoxAdapter, SliverPadding, SliverFillRemaining, SliverPersistentHeader.

Fixed list builds all.

A fixed children: list builds everything up front (no laziness). Switch to a SliverChildBuilderDelegate so only visible rows build.

Persistent header.

SliverPersistentHeader (with a SliverPersistentHeaderDelegate) — custom header that can pin/float with explicit min/max extents.

One viewport.

Slivers share one viewport (one scroll position/belt), so their geometry coordinates. Nested ListViews are separate viewports with independent scroll, so they can't collapse/scroll together.

Layout/paint/hit-test.

Layout (size + place children), paint (draw), hit testing (point-inside). RenderBox is the common 2D base. (Part 6)

Down/up/parent.

Constraints go down, sizes go up, the parent sets position. Parent passes BoxConstraints; child picks a Size; parent sets the child's offset.

Child vs parent.

The child chooses its size (within constraints); the parent chooses the child's position.

Size vs appearance.

markNeedsLayout when size/position changes; markNeedsPaint when only appearance changes (e.g. color). Repaint-only is cheaper.

Paint only.

markNeedsPaint() — color doesn't affect size/position, so no relayout.

create / update.

createRenderObject (once, on mount) and updateRenderObject (on rebuild when the Element is reused) — the latter mutates the render object in place.

Mutate in place.

When canUpdate reuses the Element, updateRenderObject updates the existing render object with new values instead of allocating a new one — so a full build() translates to minimal real work.

Leaf/Single/Multi.

LeafRenderObjectWidget (0), SingleChildRenderObjectWidget (1), MultiChildRenderObjectWidget (many).

Position/extra info.

It stores per-child data the parent owns — most commonly the child's offset (position), and layout extras (e.g. flex). The parent reads/writes it during layout/paint.

Drawing, not layout.

When you need custom drawing with no special layout — a CustomPainter is simpler and sufficient (charts, gauges, signatures).

Relayout propagation.

It declares that the parent's layout depends on the child's size, so when the child relays out the parent relays out too. Omitting it (when you don't read child size) limits relayout propagation — an optimization.

Independent invalidation.

Many changes affect only appearance, not geometry. Separate phases let Flutter repaint without relaying out (and vice versa), invalidating each independently to avoid unnecessary work.

Own layer.

Isolates a subtree onto its own paint layer, so its repaints don't force neighbors to repaint (and vice versa).

Wrap it.

Wrap the spinner in RepaintBoundary so its repaints stay on its own layer and don't dirty the chart's layer.

Infinite maxHeight.

A parent (e.g. Column) passes unbounded (infinity) max constraints down to a child that wants to fill available space (e.g. ListView). The child can't pick a finite size, so layout fails. Give it bounded constraints (Expanded, SizedBox, etc.). (constraints)

Walk + point-inside.

Flutter walks the render tree asking each object (via hitTest) whether the pointer position falls inside it (typically against its size), building the list of objects under the pointer that then receive the event.

Every layer.

setState mutates a field and markNeedsBuilds the Element (Part 1) → BuildOwner rebuilds it → build returns a new Text → canUpdate matches (type+key) so the Element is reused → updateRenderObject sets the new color on the existing RenderParagraph and calls markNeedsPaint (no relayout, since size is unchanged) → the paint phase redraws just that render object's layer. Widget → Element → RenderObject, mutated in place.

Add an identity key to each item widget:

for (final item in items) ItemTile(key: ValueKey(item.id), item: item)

Now reconciliation matches by key, so state follows the item, not the slot (Part 2).

(a) reuse, state survives. (b) replace (type), state lost. (c) replace (key differs), state lost. (d) reuse, state survives. Driven by runtimeType + key (Part 1).

Scaffold(
  body: Builder(builder: (context) => ElevatedButton(
    onPressed: () => ScaffoldMessenger.of(context)
        .showSnackBar(const SnackBar(content: Text('Hi'))),
    child: const Text('Show'),
  )),
);

The Builder provides a context below the Scaffold (Part 3).

void initState() { super.initState(); _sub = widget.channel.listen(_on); }
void didUpdateWidget(W o) { super.didUpdateWidget(o);
  if (o.channel != widget.channel) { _sub.cancel(); _sub = widget.channel.listen(_on); } }
void dispose() { _sub.cancel(); super.dispose(); }

initState sets up, didUpdateWidget reconciles the changed prop (same State reused), dispose prevents the leak (Part 4).

await api.submit();
if (!mounted) return;          // State.mounted
Navigator.of(context).pop();

After await the State may be disposed; mounted prevents "deactivated widget" errors (Part 3/Part 4).

CustomScrollView(slivers: [
  const SliverAppBar(expandedHeight: 180, pinned: true,
      flexibleSpace: FlexibleSpaceBar(title: Text('Feed'))),
  SliverList(delegate: SliverChildBuilderDelegate(
      (c, i) => ListTile(title: Text('Item $i')), childCount: 1000)),
  const SliverFillRemaining(hasScrollBody: false, child: Footer()),
]);

One viewport, lazy list, all scrolling together (Part 5).

class RenderSquare extends RenderBox {
  RenderSquare(this._c);
  Color _c;
  set color(Color v) { if (v == _c) return; _c = v; markNeedsPaint(); }
  @override
  void performLayout() => size = constraints.constrain(const Size(100, 100));
  @override
  void paint(PaintingContext context, Offset offset) =>
      context.canvas.drawRect(offset & size, Paint()..color = _c);
}

Color setter calls markNeedsPaint only — no relayout (Part 6).

class Square extends LeafRenderObjectWidget {
  const Square(this.color, {super.key});
  final Color color;
  @override
  RenderObject createRenderObject(BuildContext c) => RenderSquare(color);
  @override
  void updateRenderObject(BuildContext c, RenderSquare ro) => ro.color = color;
}

createRenderObject once; updateRenderObject mutates in place on reuse (Part 6).

Wrap the animating banner (and/or the expensive static cards) in RepaintBoundary so the animation's repaints stay on its own layer and don't dirty the cards (Part 6).

1. Hit testing (Part 6): the tap location walks the render tree; the like button's render object is found under the pointer and the gesture is dispatched.
2. Callback → setState (Part 4/State Mgmt 1): the row's State increments its count inside setState, which calls markNeedsBuild on its Element.
3. BuildOwner (Part 1): the dirty Element is rebuilt next frame in tree order.
4. Reconciliation / canUpdate (Part 1): the new widget subtree matches the old by runtimeType+key, so Elements are reused, not rebuilt. Because the list has keys (Part 2), the correct row's Element is matched by identity even though the list can reorder.
5. updateRenderObject (Part 6): the count Text's render object has its text updated in place and calls markNeedsPaint (size unchanged → no relayout, just repaint).
6. BuildContext (Part 3): any Theme.of(context) the row uses resolves upward to style the new text.
7. Layout (if size changed) (Part 6): if the new number is wider, the protocol runs — constraints down, sizes up, parent positions — but for a same-width change only paint runs.
8. Slivers (Part 5): because the feed is a lazy SliverList, only on-screen rows ever existed as Elements/RenderObjects, so this whole process touched a screen's worth of objects, not the whole list.
9. Lifecycle/leak safety (Part 4): if the like triggered async work, the callback guards with mounted before any further setState.

One tap, every layer: hit test → callback → markNeedsBuild → BuildOwner → canUpdate (+keys) → updateRenderObject → markNeedsPaint → composited frame. If you can narrate this, you understand Flutter internals.