Stateless, Stateful and build()

"One must imagine Sisyphus happy." — Albert Camus, The Myth of Sisyphus (1942)

build() is the most-executed method you will ever write. It runs when state changes, when a parent rebuilds, when the screen rotates, when a theme changes, when a dependency updates — potentially sixty times a second, producing a description that is examined, compared, and thrown away, so that it can be produced again.

Sisyphus at least got to the top of the hill. Understanding that this is fine — that the repetition is the design rather than a cost the framework is apologising for — is most of what separates people who write comfortable Flutter from people who keep trying to prevent it.

Part I established the three trees and the rule that governs them. This Part is about the one you actually write in, and this chapter is about its two kinds and the method they share.

Two kinds, and the framework's own preference

The choice between them is usually taught as a rule of thumb. The framework's own usage is more interesting than the rule.

setState is one line

The method at the centre of all this does dramatically less than its reputation suggests. Stripped of its debug assertions, State.setState in framework.dart is:

void setState(VoidCallback fn) {
  assert(() { /* … debug-only checks … */ }());
  _element!.markNeedsBuild();
}

Your closure runs — synchronously, immediately, before setState returns — and then one element is marked dirty.

The lifecycle, in order

A State object has a documented life, and knowing the order tells you where each kind of work belongs.

What a rebuild actually costs, measured

Part II claimed that const lets Flutter skip a subtree. Here is that claim measured with build counters in a real widget test rather than asserted.

Five reasons build runs

setState is the one everybody knows and it is not the only trigger. Knowing the full list is what makes the "must be pure" rule feel necessary rather than pedantic:

• setState on this widget's own State.
• A parent rebuilt, so this widget was recreated as part of the parent's new description — this is the most common cause by a wide margin, and it is entirely outside this widget's control.
• An InheritedWidget it depends on changed — a theme, a locale, a MediaQuery. Rotating the device or opening the keyboard changes MediaQuery, which rebuilds everything that reads it.
• A hot reload, which marks every element in the application dirty.
• An ancestor was rebuilt for any of the above, recursively.

Only the first is something the widget decided. The other four arrive unannounced, at moments the widget cannot predict, which is precisely why a side effect in build cannot be reasoned about — you are not writing "do this when the user taps", you are writing "do this whenever anything above me changes for any reason".

The keyboard case is the one that catches people, because it is so ordinary. Opening a keyboard changes the viewport insets, which changes MediaQuery, which rebuilds every widget that depends on it — so a request started in build fires again when the user taps a text field, and the causal chain between those two events is invisible in the code.

Narrowing what rebuilds

Given that a parent rebuilding is the dominant cause, the most effective performance technique in Flutter is not making build faster. It is arranging for less of the tree to be in it.

Three moves, in order of how often they apply:

Push state down. If only a small part of a screen depends on a changing value, extract that part into its own widget that holds the state. The counter that was in a big screen's State becomes a small StatefulWidget of its own, and now setState marks that element dirty rather than the screen's — so the rebuild covers ten widgets instead of two hundred. This is the single highest-leverage change available and it costs one class.

Make the unchanging parts const. Measured earlier: a const child of a parent rebuilt five times built once. Anything in a build method that does not depend on state or configuration should be const, and the linter will find them for you.

Lift the expensive child out as a parameter. When a widget must rebuild but contains a costly subtree that does not change, pass that subtree in rather than constructing it inside. A Builder-style widget that takes a child and rebuilds around it leaves the child object untouched, so the identity check succeeds and the subtree is skipped — this is why AnimatedBuilder takes a child argument and why using it correctly matters.

What these have in common is that none of them makes any code faster. They change what gets called, and that is almost always where the real win is, because the cheapest build method is the one that never runs.

Reaching state from outside, and why it usually hurts

Flutter does provide a mechanism for the case the decision table calls "lift it out": a GlobalKey gives you a handle to a specific element wherever it is in the tree, and GlobalKey<MyState> lets you call methods on that State directly.

It works, the framework uses it internally — Form and Scaffold both expose state this way — and in application code it is nearly always the wrong answer.

The cost is not performance, though a GlobalKey is more expensive than a local one. It is that you have created a dependency the tree does not express. A widget somewhere now reaches into a widget somewhere else and changes it, and nothing in either widget's signature says so. The compiler cannot see it, a reader cannot find it without searching for the key, and moving either widget can break it silently.

The times it is genuinely right are narrow and recognisable: validating a Form from a button outside it, or keeping a State alive while its widget moves to a different position in the tree — which only a GlobalKey can do. Everything else is usually a sign that the state wants to be above both widgets rather than inside one of them.

The lifecycle in a running widget

Toggle the child and the console shows initState and dispose firing in pairs. That pairing is the contract: everything created in the first must be released in the second, and the framework guarantees dispose runs exactly once when the element is gone for good.

Notice what the collection-if is doing there. if (showChild) const _Tracked() does not hide the widget — it removes it from the description entirely, so no widget exists at that position, so the element is unmounted and dispose runs. Wrapping it in a Visibility or an Opacity instead would keep the element mounted and its state alive, which is sometimes exactly what you want and is a completely different behaviour arrived at by a similar-looking change.

That distinction is worth holding onto, because it is the practical form of the whole chapter. A widget removed from the tree loses its state; a widget merely made invisible does not. Neither is more correct — a form you want to preserve while a section is collapsed wants the second, and a screen you want to reset wants the first — but they look almost identical in the source, and the difference only shows up in behaviour the next person has to reverse-engineer.

There is a third option worth knowing for the case where you want to keep state and stop paying for the widget: Offstage, which keeps the element mounted and its state alive while skipping paint and hit-testing. It still takes part in layout, so it is not free, but it is the middle ground between "gone" and "drawn".

Common Mistakes

1. Doing work in build. It runs constantly; anything with an effect belongs elsewhere.
2. Expecting setState to rebuild immediately. It marks the element dirty; the next frame rebuilds.
3. Thinking setState is asynchronous. The closure runs synchronously before it returns.
4. Mutating outside the closure. It works, and it severs the link between change and rebuild.
5. Passing an async closure to setState. It returns before the state changes; the framework asserts.
6. Using initState for anything that can change. It runs once; didUpdateWidget is the repair.
7. Reading an InheritedWidget in initState. Use didChangeDependencies.
8. Forgetting dispose. Every controller, subscription and timer created above must be released.
9. Making a widget stateful so others can reach its state. That means the state is in the wrong place.
10. Assuming stateless is always preferable. The framework itself has more stateful widgets than stateless.

Interview Corner

Hands-on

Summary

• build is the most-executed method you write, and the repetition is the design rather than a cost.
• The framework has more stateful widgets than stateless — 296 to 226 — because its widgets own resources.
• Prefer stateless in your own code not for cost but because state should live where fewest things see it.
• If something outside needs the state, neither answer is right. Lift it out.
• setState is one line: _element!.markNeedsBuild(). Everything else is debug assertions.
• The closure runs synchronously, so mutating outside it works — and severs the link it exists to document.
• An async closure to setState asserts, because it returns before the state has changed.
• Measured: a const child built once while the parent rebuilt five times; the non-const child built six.
• The skip is the framework not calling build at all, so the saving scales with subtree size.
• initState and dispose are a pair. Everything created in one is released in the other.

Next: The Element Tree, and What Rebuild Means — what actually happens between markNeedsBuild and a pixel changing, and why a rebuild is cheaper than the word suggests.