Inherited Data Propagation

## The problem: data needed far from where it lives In a hiking-trail app, the user picks a **unit system** once in settings: metric or imperial. That choice matters to a trail card's distance label, an elevation chart's axis, a pace field on the recording screen and a weather tile, all several levels below the screen that owns the setting. Without a sharing mechanism you pass `units` through every intermediate constructor. That is **prop drilling**, and it has three costs: - every widget on the path gains a parameter it never reads; - adding one more consumer means editing every ancestor on its path; - when the value changes, the whole path rebuilds, because each constructor argument changed. `InheritedWidget` is Flutter's built-in answer. It is the primitive under `Theme`, `MediaQuery`, `Directionality`, `DefaultTextStyle` and many package-level scopes. ## How you declare one An `InheritedWidget` subclass has three parts: 1. **Immutable data** in `final` fields, plus the required `child` passed to the super constructor. 2. **Static accessors** by convention: `maybeOf(context)` returns `null` when no ancestor exists; `of(context)` asserts or throws with a helpful message instead. Both call `context.dependOnInheritedWidgetOfExactType<T>()`. 3. **`updateShouldNotify(oldWidget)`**, which the framework calls when the widget at this position is replaced by a new instance. It receives the previous widget, which is guaranteed to have the same `runtimeType`, and returns whether dependents need to rebuild. ```dart class UnitsScope extends InheritedWidget { const UnitsScope({super.key, required this.units, required super.child}); final UnitSystem units; static UnitSystem of(BuildContext context) => context.dependOnInheritedWidgetOfExactType<UnitsScope>()!.units; @override bool updateShouldNotify(UnitsScope oldWidget) => units != oldWidget.units; } ``` ## What the framework does with it Each element keeps a map from widget `runtimeType` to the nearest **`InheritedElement`** of that type, inherited from its parent. So finding the nearest `UnitsScope` is a constant-time map lookup, not a walk up the tree. Because the map is keyed by the **exact** runtime type, a subclass of `UnitsScope` would not be found by `dependOnInheritedWidgetOfExactType<UnitsScope>()`. The lookup does two things: - it returns the widget, so the caller can read `units`; - it adds the calling element to the `InheritedElement`'s set of **dependents**. When the scope is rebuilt with a new instance and `updateShouldNotify` returns `true`, the `InheritedElement` calls `didChangeDependencies` on every dependent, which marks each one for rebuild in the next build phase. For a `StatefulWidget` dependent, `State.didChangeDependencies` runs before its next `build`. | Widget in the subtree | Rebuilt when units change? | |---|---| | Called `UnitsScope.of(context)` in build | Yes | | Did not call it, and its parent passed the same widget instance | No | | Did not call it, but its parent was itself rebuilt | Yes, through the ordinary parent rebuild | ## One toggle, step by step Suppose the user switches from metric to imperial on the settings screen: 1. The settings `State` above `UnitsScope` calls `setState` with `UnitSystem.imperial`. 2. In the next build phase that `State` rebuilds and returns a **new** `UnitsScope` instance carrying `imperial` and the same `child`. 3. The `InheritedElement` receives the new widget and calls `updateShouldNotify(oldWidget)`; `imperial != metric`, so it returns `true`. 4. Every registered dependent, such as each `TrailDistance` label, gets `didChangeDependencies` and is marked dirty. 5. The child subtree is compared as usual; because the `child` instance is unchanged, the intermediate list, cards and padding are skipped. 6. The dirty dependents rebuild in the same build phase, read `UnitsScope.of(context)` again and show miles. Nothing between the scope and the labels had to know that units exist, which is the whole point. ## Where the changing value comes from Widgets are immutable, so `UnitsScope` cannot change its own `units`. The usual shape is a `StatefulWidget` above it that holds the current value in its `State`, calls `setState` when the user toggles it, and returns `UnitsScope(units: _units, child: widget.child)` from `build`. Because `widget.child` is the same instance on each rebuild, the subtree between the scope and its dependents is skipped; only dependents rebuild. ## Common mistakes to avoid - Calling the accessor from a `BuildContext` that sits **above** the scope, for example in the same `build` method that creates it. The lookup only sees ancestors of that context, so it does not find a scope created below it. - Returning `true` unconditionally from `updateShouldNotify`, which rebuilds every dependent on every rebuild of the scope even when nothing changed. - Storing a **mutable** object and changing a field in place: no new widget instance is created, so `updateShouldNotify` is never called and nothing rebuilds. ## Where it sits among neighbours Packages such as Provider wrap this primitive with lifecycle management and are their own topic. Holding changing values in a `ChangeNotifier` or `ValueNotifier` is also its own topic. What stays here is the primitive itself: immutable data, a registering lookup and a notify rule.