---

name: flutter-widget-architect description: Architects Flutter widget trees and Riverpod or Bloc state so rebuilds are scoped, build() stays pure, and const widgets skip recomposition. Use when someone asks "why is my Flutter screen janky", "should I use Riverpod or Bloc", "my whole page rebuilds when one field changes", or is building or refactoring Flutter screens, wiring StatelessWidget/StatefulWidget, Consumer, or BlocBuilder. Do NOT use for Android Jetpack Compose UI - use jetpack-compose-builder instead; do NOT use for React Native - use react-native-pro instead. metadata: title: "Flutter Widget Architect"

Flutter Widget Architect

Structure Flutter widget trees and state so rebuilds start and stop exactly where intended and build() is a pure, cheap function of state. The costly failure this prevents is the rebuild storm: one text field changes, the entire screen re-runs build(), the frame budget blows past 16ms (60fps) or 8ms (120fps), and the user sees jank that profiling later traces to architecture, not to any single slow line.

Operating procedure

Order matters: decompose before optimizing subscriptions, because .select on a monolithic build() buys nothing.

Step 1: Gather inputs

Before restructuring a screen, establish:

1. The screen or widget in question and where jank or excessive rebuilds appear (default: run DevTools rebuild tracking or debugPrintRebuildDirtyWidgets first and capture which widgets rebuild).
2. Existing state management - Riverpod, Bloc, provider, setState, or a mix (a mix inside one feature is itself the finding).
3. Which state is local-ephemeral (a toggle, one text field) vs shared/async/tested.
4. List sizes - anything that can exceed roughly 30 items must be lazy.

Label any performance claim not backed by DevTools as a guess.

Step 2: Decompose into widget classes, not methods

Split a deep build() into small StatelessWidget/StatefulWidget subclasses. Never extract subtrees into _buildX() helper methods - a helper always re-runs with its enclosing build(), while a separate const widget is skipped entirely when its inputs are unchanged. Mark const everywhere the analyzer allows; every const constructor is a subtree the framework never revisits.

Bad - the header re-runs every time the counter changes, because it is just a method on the same build:

class ProfileScreen extends ConsumerWidget {
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return Column(children: [
      _buildHeader(),            // re-executes on every count change
      Text('$count'),
    ]);
  }
  Widget _buildHeader() => Row(children: [Icon(Icons.person), Text('Profile')]);
}

Good - the header is a const class; the framework short-circuits it, and only the Text depending on the counter rebuilds:

class ProfileScreen extends ConsumerWidget {
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return Column(children: [
      const _ProfileHeader(),    // const: skipped when inputs unchanged
      Text('$count'),
    ]);
  }
}

class _ProfileHeader extends StatelessWidget {
  const _ProfileHeader();
  Widget build(BuildContext context) =>
      const Row(children: [Icon(Icons.person), Text('Profile')]);
}

Step 3: Keep build() pure

build() must read state and return widgets - no network calls, timers, setState, or controller allocation. Create AnimationController, TextEditingController, StreamSubscription, and similar in initState or a provider, and dispose every one in dispose. A controller allocated in build() leaks one instance per rebuild.

Step 4: Pick one state tool and scope it

• Riverpod for dependency-injected, testable state; use autoDispose for screen-scoped data so leaving the screen releases it.
• Bloc for explicit event-to-state transitions over an auditable stream.
• StatefulWidget + setState for purely local ephemeral UI state (a toggle, one text field) - do not reach for a global store.
• Never mix Riverpod and Bloc inside one feature; two sources of truth for one screen is a bug factory.

Step 5: Watch the narrowest unit

Subscribe to one field with ref.watch(provider.select((s) => s.field)) or a Bloc buildWhen, never the whole model - watching the model rebuilds on every unrelated field change. Use ref.read for one-shot actions inside callbacks, never to react to changes.

Step 6: Stop rebuilds at the boundary

Wrap only the changing subtree in Consumer/BlocBuilder/ValueListenableBuilder, and leave the static shell (AppBar, background, scaffold chrome) outside it. Pass child through builders to reuse subtrees the rebuild does not touch.

Step 7: Build lists lazily with stable keys

Use ListView.builder/SliverList so off-screen items are never built; a mapped Column or ListView(children: [...]) builds every item up front. Give items a ValueKey on the model id so element and state survive reorder.

Step 8: Bound your layout

Wrap flexible children in Expanded/Flexible inside Column/Row to prevent unbounded-height constraints, overflow errors, and layout thrash.

Deliverable

Produce a restructured screen containing: widget-class decomposition with const constructors, controllers created in initState/providers and disposed, one state tool scoped per Step 4, .select/buildWhen on every subscription, builders wrapping only changing subtrees, lazy keyed lists, and a before/after DevTools rebuild capture proving the static shell no longer rebuilds.

Do NOT

• Do NOT extract subtrees into _buildX() helper methods that return Widget - they cannot be skipped, const classes can.
• Do NOT do work in build() (I/O, timers, allocation, setState) - build() may run every frame.
• Do NOT ref.watch a whole model when you depend on one field; use .select/buildWhen.
• Do NOT call setState on a large State to update one value; isolate it with ValueListenableBuilder or a scoped provider.
• Do NOT leave a ListView/Column building every item or with unbounded height.
• Do NOT introduce Riverpod and Bloc into the same feature.

Quality bar

• The static shell does not rebuild when a single value changes - verified with debugPrintRebuildDirtyWidgets or DevTools rebuild tracking, not by inspection.
• Every controller, subscription, and AnimationController created is disposed; flutter analyze reports no dispose or prefer_const_constructors warnings.
• Long or unbounded lists use a lazy builder, never a mapped Column/ListView(children: [...]).
• State scope matches sharing: local state stays in StatefulWidget; shared/async/tested state lives in a provider or Bloc.
• Frames stay inside the 16ms budget (8ms at 120Hz) on a profile build for the interaction that was janky.