It marks something dirty. See Part 1.

It runs your callback (mutate fields), marks the State's element dirty via markNeedsBuild(), and returns. Flutter rebuilds that State's build() on the next frame. It doesn't paint anything itself.

UI is a function of...

UI = f(state) — the screen is a function of state; change state, re-run build(), get new pixels.

No dirty flag.

It mutates n but never calls setState, so the element is never marked dirty and build() never re-runs. Use setState(() => n++).

Which widget type?

Inside a State object (of a StatefulWidget). A StatelessWidget has no setState.

Widget might be gone.

final d = await api.get();
if (!mounted) return;
setState(() => _d = d);

mounted guards against calling setState after dispose().

When does the rebuild happen?

The callback runs synchronously, but the rebuild is deferred to the next frame — asynchronous in effect. The new tree doesn't exist on the next line.

setState during build.

Calling setState during build schedules a rebuild during a build → "setState() called during build" error/loop. Never call it in build; trigger state changes from callbacks or lifecycle methods.

Scope of the rebuild.

It rebuilds the entire build() of the State, including expensive children that didn't change.

Scope down / const.

(1) Extract the counter into its own small StatefulWidget so setState is scoped to it. (2) Make Chart const/cached so it's skipped on rebuild. (Or adopt a state solution that rebuilds only the counter.)

A lifecycle flag.

A State flag: true while the State is in the tree, false after dispose(). Used to guard async setState.

Intent + ordering.

It makes intent clear ("these changes cause this rebuild") and ensures the mutation happens before the dirty flag is acted on. Mutating outside and calling setState(() {}) works but is a smell.

It only rebuilds one owner.

It can only rebuild the widget that owns the state. Sharing across distant widgets forces lifting state up and prop-drilling it through every layer — boilerplate, coupling, over-rebuilding, tangled ownership. It has no way for a far widget to read the state directly.

Local, ephemeral.

E.g. a password obscure toggle, an expand/collapse flag, an animation value, a focus state — local UI state owned by one widget.

It doesn't diff.

Yes — setState just marks dirty; it doesn't diff your fields. A no-op setState(() {}) still triggers a (wasted) rebuild.

Threading through ancestors.

Passing shared state down through every intermediate widget via constructors. It creates boilerplate (params widgets don't use), tight coupling (one change touches many files), over-rebuilding (top-level setState), and unclear ownership.

Lift + thread.

Lift themeMode (and a toggle callback) to a common ancestor's State, then thread both through every intermediate constructor to each consumer — prop drilling. This motivates InheritedWidget/Provider (Part 2).

Pull, not push.

It lets any descendant read shared state directly via of(context) instead of prop-drilling, and rebuilds only the readers when it changes.

Reading from above.

You're reading an InheritedWidget above you in the tree, by type, via BuildContext (e.g. Theme.of, MediaQuery.of).

Reading is subscribing.

By calling context.dependOnInheritedWidgetOfExactType<T>() — the read itself registers the element as a dependent. No separate subscribe call.

Who rebuilds.

When the InheritedWidget is rebuilt, it decides whether dependents rebuild: true → all dependents rebuild; false → none. Returning true only on real changes prevents wasted rebuilds.

dependOn + assert.

static Settings of(BuildContext context) {
  final s = context.dependOnInheritedWidgetOfExactType<Settings>();
  assert(s != null, 'No Settings found');
  return s!;
}

What does it return?

No — returns false, so no dependent is notified even though a new instance was created.

Subscribe vs not.

dependOn... subscribes (registers a dependency, rebuilds on change) — use in build. get... reads without subscribing — use in callbacks/initState.

Something above rebuilds it.

A StatefulWidget (or InheritedNotifier with a Listenable) above it holds the mutable state and, on change, rebuilds the InheritedWidget with new data; updateShouldNotify then triggers dependent rebuilds.

Theme, MediaQuery...

Theme.of, MediaQuery.of, Navigator.of, DefaultTextStyle.of — and Provider/Riverpod's scope are built on it.

Elements cache by type.

Each Element keeps a map of in-scope InheritedWidgets by type, so dependOnInheritedWidgetOfExactType<T>() is a map lookup, not a linear ancestor scan.

Listenable bridge.

It wraps a Listenable (e.g. ChangeNotifier) and rebuilds dependents whenever the notifier fires — no manual updateShouldNotify diffing. It's basically how ChangeNotifierProvider works internally.

No bookkeeping.

It removes a whole class of bugs: you can't read a value and forget to subscribe (or subscribe and forget to read). The dependency is established exactly when and where you use the value.

Dependent + updateShouldNotify.

Whenever Settings is rebuilt and updateShouldNotify returns true (e.g. darkMode changed). It's a registered dependent because it read via of.

Boilerplate per value.

Each value needs an InheritedWidget, a StatefulWidget wrapper, the of method, updateShouldNotify, and a mutation API. Repeated across many values it's huge boilerplate — which is why Provider/Riverpod exist.

A subtree.

A child (the subtree it wraps and exposes data to), passed via super.child.

setState rebuilds the inherited widget.

class _CounterScopeState extends State<CounterScope> {
  int _n = 0;
  void inc() => setState(() => _n++);
  @override
  Widget build(BuildContext context) =>
      _CounterInherited(n: _n, inc: inc, child: widget.child);
}

The State owns mutation; each change rebuilds the inherited widget with a new n.

Wraps Part 2.

A package that wraps InheritedWidget (plus notifiers) with a clean API, removing the hand-written boilerplate for shared state.

The 🔔.

Missing notifyListeners() after the mutation. Add it so listeners rebuild.

build vs callbacks.

watch in build() (subscribe, rebuild on change); read in callbacks/initState (one-off, no subscription).

Wrong API in callback.

onPressed: () => context.read<Cart>().add('x') — callbacks use read, not watch.

One slice.

They subscribe to a derived slice and rebuild only when that slice changes, not on every notifyListeners() — avoiding over-rebuilding.

Who disposes.

create: lets Provider own and dispose a freshly built object (common case). .value is for an instance owned elsewhere (Provider won't dispose it). Misusing .value with a new object risks leaks.

Multi.

MultiProvider(providers: [...], child: ...).

Built once.

The child doesn't depend on the model; Consumer builds it once and reuses it across rebuilds, keeping that subtree out of the rebuild path.

Plain.

Provider<T> — for DI of a value/service (e.g. an ApiClient) that doesn't notify.

Type lookup via tree.

Provider resolves by type through the BuildContext/tree, which the compiler can't check. If no provider of that type is above, it compiles but throws at runtime — no compile-time safety.

Nearest by type.

Lookups are by type, so the tree can only find "the nearest int" — two providers of the same type are ambiguous.

dependOn vs get.

watch ↔ dependOnInheritedWidgetOfExactType (subscribe); read ↔ getInheritedWidgetOfExactType (no subscription).

Depends on another.

Creates a provider whose value depends on another provider, recomputing when the dependency changes.

Notifies.

A ChangeNotifier that calls notifyListeners() on change.

select.

final name = context.select<UserModel, String>((u) => u.name);

Now only name changes trigger a rebuild.

create.

When you use create:, Provider calls dispose() on the created ChangeNotifier when the provider leaves the tree — no manual cleanup.

Runtime, type, context.

Runtime dependency errors (ProviderNotFoundException), type collisions (same-type providers), and BuildContext dependence (can't easily read state outside widgets) — all fixed by Riverpod.

Out of the tree.

Providers are top-level objects referenced by name (via ref), not widgets looked up by type via context. Compile-safety, no context, and no type collisions all follow.

A small object.

A ref (WidgetRef in widgets, Ref in providers): ref.watch / ref.read / ref.listen.

Reference by name.

Providers are top-level variables referenced directly; referencing a non-existent one fails to compile, unlike Provider's runtime type lookup.

.notifier for methods.

ref.watch(cartProvider).count;
ref.read(cartProvider.notifier).add('x');

Identity, not type.

Riverpod keys providers by identity (the variable), so type is irrelevant — two int providers are distinct.

subscribe / once / side-effect.

watch = subscribe in build (Part 3 watch, Part 2 dependOn); read = one-off in callbacks (Part 3 read); listen = run side-effects on change.

No context.

A provider can ref.watch other providers without BuildContext, so business logic composes and tests outside the widget tree. Provider needs a context.

Exhaustive switch.

A single value with data/loading/error to pattern-match, forcing the UI to handle all three states and removing manual isLoading booleans. See AsyncValue.

family.

.family — e.g. userProvider(id). See family.

Tear down.

Disposes the provider's state when nothing is listening, with keepAlive to cache when needed. See autoDispose.

Scope.

ProviderScope — runApp(const ProviderScope(child: MyApp())). See ProviderScope.

Consumer.

ConsumerWidget (or ConsumerStatefulWidget), whose build receives (context, ref).

The container.

ProviderScope uses an InheritedWidget to hold the provider container and expose WidgetRef. Your providers are top-level objects; the container lives in the scope.

build_runner.

A code-generation API (Riverpod 3.0) that generates providers from annotated functions/classes, powered by build_runner (metaprogramming). The manual API is what it compiles to.

ref.watch another provider.

final totalProvider = Provider<int>((ref) {
  final cart = ref.watch(cartProvider);
  return cart.items.fold(0, (s, i) => s + i.price);
});

Same name.

ref.watch(provider.select((s) => s.slice)) — rebuilds only when the selected slice changes.

Compile-time + context-free.

Compile-time safety (no runtime ProviderNotFound) and no BuildContext dependence (read via ref, usable/testable outside widgets), plus AsyncValue/family/autoDispose ergonomics.

One direction.

UI triggers a change → business logic produces a new immutable state → UI rebuilds. The UI never mutates state directly.

Methods vs events.

Cubit triggers changes with methods (emit inside them); Bloc uses events (add(event) → on<Event>), giving a traceable event log.

super(0), emit.

class CounterCubit extends Cubit<int> {
  CounterCubit() : super(0);
  void increment() => emit(state + 1);
}

Mutates in place.

It mutates the existing list and emits the same instance; equality-based change detection may skip the rebuild and immutability is violated. Use emit([...state, t]).

on<Increment>.

class Increment extends CounterEvent {}
// in constructor:
on<Increment>((e, emit) => emit(state + 1));
// UI: context.read<CounterBloc>().add(Increment());

rebuild / effect / both.

BlocBuilder rebuilds UI from state; BlocListener runs side-effects (snackbar/nav) once per transition without rebuilding; BlocConsumer does both.

Once per transition.

In BlocListener — side-effects must fire once per state change. BlocBuilder can rebuild repeatedly, causing duplicate snackbars.

Exhaustiveness.

The compiler forces the UI's switch to handle every state (loading/loaded/error), so no case is forgotten — unlike nullable-field states that can drift into invalid combinations.

Part 2.

An InheritedWidget under the hood — the same mechanism Provider uses to expose the Bloc/Cubit to the subtree.

Gate.

Predicates that gate whether BlocBuilder rebuilds / BlocListener fires for a given transition — Bloc's version of select-style precision.

add vs method.

Bloc: context.read<MyBloc>().add(SomeEvent()). Cubit: context.read<MyCubit>().someMethod().

Audit trail vs boilerplate.

A named, ordered, loggable event trail of user actions (great for complex/auditable flows, debugging, replay). The cost is more boilerplate (event classes + handlers) — overkill for simple state.

Similar but stricter.

Both hold state and notify. Cubit's state is immutable and replaced via emit (vs mutate-then-notifyListeners), and it plugs into Bloc tooling/observers.

Sealed switch.

switch (state) {
  WeatherInitial() => const Text('Search'),
  WeatherLoading() => const CircularProgressIndicator(),
  WeatherLoaded(:final temp) => Text('$temp°'),
  WeatherError(:final message) => Text(message),
}

Simple → complex.

Start with Cubit for simple state; move a feature to Bloc when its event history/traceability becomes valuable (complex flows). Mixing both in one app is normal.

DIY vs built-in.

Both enforce exhaustive multi-state handling. AsyncValue is built-in (data/loading/error); Bloc has you define states yourself — more verbose but fully customizable. See AsyncValue.

Equality.

Bloc compares old/new states (by identity/equality). Mutating in place keeps the same instance, so the change may be undetected and the rebuild skipped. A new object (or proper ==/Equatable) ensures the transition registers.

Scope.

Local to one widget, or shared across widgets? Local → setState; shared → a state-management solution.

Ephemeral local.

For local, ephemeral UI state owned by one widget (toggles, focus, animations). A framework there is over-engineering.

Ceremony, no payoff.

The state is trivial and local, so events/states/handlers add ceremony with no benefit. setState is correct and clearer.

Under-engineering.

It threads shared state through many widgets (boilerplate, coupling, over-rebuilds). Shared state belongs in a state solution read directly via watch/ref.watch.

Compile + context.

Compile-time safety and no BuildContext dependence (plus AsyncValue ergonomics).

Big team, complex flow.

Large apps/teams with complex, auditable flows needing predictability and an event trail.

DI.

A plain Provider<T> (Provider package) or a Riverpod Provider — dependency injection of a service.

Mix.

No — pick a primary shared-state solution for consistency, but use setState freely for local UI. Mixing by scope is healthy.

Where, not how little.

The framework moves where state lives, not how little you rebuild. You still scope subscriptions (select/buildWhen), use const, and keep build() light (efficiency).

AsyncValue.

Riverpod with AsyncValue (FutureProvider/AsyncNotifier) for exhaustive loading/data/error handling.

Don't rewrite.

Stay on Provider — it's fine to maintain; don't rewrite working code without a real reason.

Structure/ceremony.

From setState → Provider → Riverpod → Bloc, structure, power, and ceremony increase. More structure pays off as apps/teams grow; it's overhead on small projects.

AsyncValue / sealed.

Riverpod via built-in AsyncValue; Bloc via self-defined sealed state classes. Both force handling loading/data/error.

Discipline.

If widgets watch whole chunky objects instead of narrow slices, many rebuild on unrelated changes. Performance comes from scoping subscriptions and using const, not from the tool itself.

Events.

Bloc — each step is a named event, yielding an ordered, loggable trail for debugging/replay.

Both good.

Both are excellent. Riverpod is more concise and compile-safe with less ceremony; Bloc is more prescriptive with one obvious pattern and an event trail. The choice is often team culture, not correctness.

Match tool to scope.

Match the tool to the state's scope and the app's complexity — setState for local UI, a single shared solution (Provider/Riverpod/Bloc) for app-wide state — and stay disciplined about rebuilding only what changed.

class Counter extends StatefulWidget {
  const Counter({super.key});
  @override
  State<Counter> createState() => _CounterState();
}
class _CounterState extends State<Counter> {
  int _n = 0;
  @override
  Widget build(BuildContext context) => ElevatedButton(
    onPressed: () => setState(() => _n++),
    child: Text('$_n'),
  );
}

setState mutates _n and marks the element dirty; Flutter re-runs build() next frame with the new value (Part 1).

class CounterScope extends StatefulWidget {
  const CounterScope({super.key, required this.child});
  final Widget child;
  static _Inherited of(BuildContext c) =>
      c.dependOnInheritedWidgetOfExactType<_Inherited>()!;
  @override
  State<CounterScope> createState() => _CounterScopeState();
}
class _CounterScopeState extends State<CounterScope> {
  int _n = 0;
  @override
  Widget build(BuildContext context) => _Inherited(
    count: _n,
    increment: () => setState(() => _n++),
    child: widget.child,
  );
}
class _Inherited extends InheritedWidget {
  const _Inherited({required this.count, required this.increment, required super.child});
  final int count;
  final VoidCallback increment;
  @override
  bool updateShouldNotify(_Inherited old) => count != old.count;
}

Descendants call CounterScope.of(context).count / .increment() — no prop drilling (Part 2).

class CartModel extends ChangeNotifier {
  final _items = <String>[];
  int get count => _items.length;
  void add(String i) { _items.add(i); notifyListeners(); }
}

ChangeNotifierProvider(create: (_) => CartModel(), child: const Shop());

// badge:
Selector<CartModel, int>(
  selector: (_, c) => c.count,
  builder: (_, count, __) => Text('Cart ($count)'),
);
// button:
onPressed: () => context.read<CartModel>().add('Apple');

Selector scopes the rebuild to count; read fires the method (Part 3).

class CartNotifier extends Notifier<List<String>> {
  @override
  List<String> build() => [];
  void add(String i) => state = [...state, i];
}
final cartProvider = NotifierProvider<CartNotifier, List<String>>(CartNotifier.new);

// badge (rebuild only on count):
final count = ref.watch(cartProvider.select((c) => c.length));
// button:
onPressed: () => ref.read(cartProvider.notifier).add('Apple');

Compile-safe, no context; select scopes the rebuild (Part 4).

sealed class WState {}
class WInitial extends WState {}
class WLoading extends WState {}
class WLoaded extends WState { WLoaded(this.t); final double t; }
class WError extends WState { WError(this.m); final String m; }

class WeatherCubit extends Cubit<WState> {
  WeatherCubit(this._api) : super(WInitial());
  final WeatherApi _api;
  Future<void> fetch(String city) async {
    emit(WLoading());
    try { emit(WLoaded(await _api.getTemp(city))); }
    catch (e) { emit(WError('$e')); }
  }
}

// UI:
BlocBuilder<WeatherCubit, WState>(builder: (_, s) => switch (s) {
  WInitial() => const Text('Search'),
  WLoading() => const CircularProgressIndicator(),
  WLoaded(:final t) => Text('$t°'),
  WError(:final m) => Text(m),
});

(Part 5)

sealed class WEvent {}
class FetchWeather extends WEvent { FetchWeather(this.city); final String city; }

class WeatherBloc extends Bloc<WEvent, WState> {
  WeatherBloc(this._api) : super(WInitial()) {
    on<FetchWeather>((e, emit) async {
      emit(WLoading());
      try { emit(WLoaded(await _api.getTemp(e.city))); }
      catch (err) { emit(WError('$err')); }
    });
  }
  final WeatherApi _api;
}
// UI: context.read<WeatherBloc>().add(FetchWeather('London'));

Now each fetch is a loggable event (Part 5).

BlocBuilder<CounterBloc, int>(
  buildWhen: (prev, curr) => curr.isEven,
  builder: (_, count) => ExpensiveWidget(count),
);

buildWhen gates the rebuild (Part 5).

BlocListener<OrderBloc, OrderState>(
  listener: (context, state) {
    if (state is OrderPlaced) Navigator.of(context).pushNamed('/success');
  },
  child: const OrderView(),
);

Navigation is a side-effect that must run once per transition; BlocBuilder can rebuild repeatedly and cause duplicate navigations (Part 5).

(a) Riverpod/Provider notifier — shared, reactive theme. (b) setState — local UI animation. (c) Riverpod (new app) — shared, compile-safe session. (d) Bloc — event audit trail for the flow. Match tool to scope/complexity (Part 6).

// 1. ROOT: Riverpod for shared app state (todos), compile-safe, no context (Part 4).
final todosProvider = NotifierProvider<TodosNotifier, List<Todo>>(TodosNotifier.new);
class TodosNotifier extends Notifier<List<Todo>> {
  @override
  List<Todo> build() => [];
  void add(Todo t) => state = [...state, t];
  void toggle(String id) =>
      state = [for (final t in state) if (t.id == id) t.copyToggled() else t];
}

// 2. A list tile uses setState for its LOCAL expand animation (Part 1) —
//    purely local UI, no business state involved.
class _TileState extends State<TodoTile> {
  bool _expanded = false;
  @override
  Widget build(BuildContext context) => Column(children: [
    ListTile(onTap: () => setState(() => _expanded = !_expanded)),
    if (_expanded) const TodoDetails(),
  ]);
}

// 3. The app bar badge watches only the count via select — scoped rebuild
//    (Parts 3/4 select; the rebuild discipline of Part 6 / efficiency).
final count = ref.watch(todosProvider.select((list) => list.length));

// 4. A shared ApiClient injected as a plain Provider — DI, no reactivity (Part 6).
final apiProvider = Provider<ApiClient>((ref) => ApiClient());

// 5. For a complex "sync to server" flow with retries you want auditable,
//    a Cubit/Bloc with sealed Syncing/Synced/SyncFailed states (Part 5) —
//    each step traceable, exhaustive UI switch.

Concept map:

• Riverpod NotifierProvider for the shared todo list — Part 4: compile-safe, context-free shared state, built on the InheritedWidget container of Part 2.
• setState for the local expand animation — Part 1: correct for ephemeral local UI.
• select for the badge — Part 3/Part 4: rebuild only on the slice, the discipline from Part 6.
• Plain Provider for the ApiClient — dependency injection of a service.
• Cubit/Bloc for the auditable sync flow — Part 5: sealed states + (optionally) events for traceability.

If you can justify why each tool fits its piece, you've mastered the series' real lesson: match the tool to the state.