flutter-performance

Flutter Performance

Hold a steady 60 fps (<=16 ms/frame; <=8 ms on 120 Hz) on a floor device (low-end Android / older iPhone). Performance is a property you measure in profile mode, not one you assert. It comes from rebuilding less, painting cheaply, and keeping both the UI thread and the raster thread free.

Non-negotiable rules

1. `const` everything legal. A const subtree is skipped on rebuild — the framework short-circuits it by identity. Keep prefer_const_constructors on as an error; a non-const literal that could be const is a lint failure, not a preference.
2. Shrink the rebuild scope to the smallest changing widget. Never ref.watch(provider) for a whole state object when one field changed — watch provider.select((s) => s.field). A HUD counter tick must never rebuild a heavy sibling. Rebuild scope is the single biggest lever on build-thread cost.
3. Lazy everything long. ListView.builder / GridView.builder / slivers for variable or unbounded content. ListView(children: items.map(...).toList()) builds every off-screen row up front — refuse it for anything not tiny and fixed.
4. No expensive work in `build()`. No jsonDecode, sort, regex, DateTime math, file/network, or large allocation — build() may run every frame. Compute in the Notifier/ViewModel once and cache the result in immutable state.
5. Heavy CPU off the UI isolate. Parse large payloads, process images, crunch numbers in compute() or a spawned Isolate. Blocking the UI thread is guaranteed jank; the raster thread cannot save you.
6. Size image decode to the display slot. cacheWidth/cacheHeight or ResizeImage, correct asset resolutions, precacheImage for above-the-fold art. Decoding a 4000 px source into a 100 px box spikes memory and OOMs cheap phones.
7. Prefer the cheapest widget that does the job. ColoredBox/DecoratedBox over Container, SizedBox for spacing, FadeTransition/AnimatedOpacity over the Opacity widget in hot paths. Avoid ClipPath/saveLayer inside scrolling lists — they force an offscreen buffer on the raster thread.
8. `RepaintBoundary` around costly, independently-repainting subtrees (an animation, a chart, a live indicator) so its repaint does not re-raster its neighbours. Do not sprinkle boundaries everywhere — each is a compositor layer that costs memory.
9. Pass expensive children through `child:`. AnimatedBuilder/ValueListenableBuilder/StreamBuilder rebuild only the builder; hand the unchanging subtree in via child: so it is built once, not per frame.
10. Dispose to avoid leaks. AnimationControllers, gesture recognizers, stream subscriptions, timers, TextEditingControllers, caches — released in dispose() (widgets) or ref.onDispose (providers). autoDispose scoped session state so it does not survive the screen.
11. Measure in PROFILE mode on a real floor device with DevTools. Debug timings are meaningless (JIT, asserts). Watch the raster thread as well as the UI thread — saveLayer/blur/clip cost shows there, not in Dart. Never ship a frame-budget number that was asserted, not measured.

Narrow the rebuild scope

Watch the single field that changes, not the whole state object:

// Rebuilds only when the count changes, not on every OrderState mutation.
class OrderBadge extends ConsumerWidget {
  const OrderBadge({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(orderProvider.select((s) => s.items.length));
    return Text('$count');
  }
}

.select runs the selector every publish but rebuilds only when the selected value's == changes, so its input must be an immutable value with real equality. See state-management-riverpod for the watch/read/listen split and family + autoDispose.

Keep expensive children out of the animation loop

// The card is built once; only the transform recomputes each tick.
AnimatedBuilder(
  animation: _controller,
  child: const ProductCard(),
  builder: (_, child) =>
      Transform.scale(scale: _controller.value, child: child),
);

Lazy lists and sized images

// Lazy — only visible rows are built.
ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, i) => ItemTile(item: items[i]),
);

// Decode to the slot, not the source resolution.
Image.asset('assets/hero.png', cacheWidth: 240);

Heavy work off the UI isolate

// parseItems is a top-level or static function (isolate entry-point rules).
final items = await compute(parseItems, jsonString);

Custom painting

For a CustomPainter, the discipline is zero-allocation paint(), a shouldRepaint that is one value comparison over an immutable scene value, and a repaint: Listenable (the AnimationController) instead of setState in a ticker. That treatment lives in custom-canvas-and-gestures; the one performance-critical rule to carry here: never allocate `Paint`/`Path`/`Gradient` inside `paint()` — hold them as painter fields and mutate cheap properties.

Profiling workflow

1. flutter run --profile on a physical floor device.
2. DevTools -> Performance; record while reproducing the jank.
3. For each over-budget frame, check whether the time is in Build, Layout, or Raster.

• Build-heavy -> narrow rebuild scope with .select, add const, move work out of build().
• Raster-heavy -> reduce Opacity/clips/saveLayer, add a RepaintBoundary, simplify shaders.

1. Use "Track widget rebuilds" to find widgets rebuilding too often.
2. Fix one bottleneck, re-measure. Never optimize without a before/after measurement.

Anti-patterns

• Judging performance in debug mode — JIT and asserts make timings fiction. Profile mode, real device, always.
• Premature optimization with no profile data — adds complexity, hides nothing; measure first.
• `setState()` high in the tree rebuilding a whole screen for a tiny change — scope the state down.
• `ref.watch(provider)` for a whole object in a leaf when one field changed — use .select.
• `ListView(children: [...].toList())` for long/unbounded content — builds every off-screen row.
• `jsonDecode`/sort/`DateTime` math/regex in `build()` — it may run every frame; precompute in the ViewModel.
• `Opacity` widget for fades in scrolling lists — forces saveLayer; use FadeTransition or fade via color.
• Decoding full-resolution images into small widgets — memory spikes and OOM on cheap phones.
• Parsing large payloads / heavy loops on the UI isolate — frozen frames; use compute.
• `RepaintBoundary` on everything — layer-memory bloat; use it surgically around independently-repainting subtrees.
• `AnimatedBuilder`/`StreamBuilder` rebuilding an expensive child instead of passing it via child:.
• Rebuilding on every keystroke without debounce, or unbounded caches/listeners that leak.
• Allocating `Paint`/`Path` inside `paint()` — per-frame garbage; hold them as fields.

Definition of done

• [ ] const applied everywhere legal; prefer_const_constructors clean.
• [ ] Rebuilds scoped with .select; a tick in one widget never rebuilds a heavy sibling.
• [ ] Long/variable lists are lazy (.builder/slivers).
• [ ] No I/O, parsing, or heavy compute in build(); big work runs via compute/Isolate.
• [ ] Images sized to display (cacheWidth/ResizeImage); above-the-fold precached.
• [ ] Cheapest suitable widgets/effects chosen; RepaintBoundary used surgically; expensive children passed via child:.
• [ ] Any CustomPainter allocates nothing in paint(); shouldRepaint is one value compare.
• [ ] Controllers, recognizers, subscriptions, timers disposed; scoped session state autoDisposed; no leaks.
• [ ] Measured in profile mode on a floor device via DevTools — UI and raster threads under budget; no frames over 16 ms; claim backed by a recording.

Related skills

• state-management-riverpod — the watch/read/listen split, .select, family + autoDispose, immutable state that makes .select correct.
• widget-composition — small const Widget classes over _buildX methods, dispose discipline, cheapest-widget choices.
• custom-canvas-and-gestures — zero-allocation paint(), shouldRepaint as one value compare, repaint: Listenable.
• testing-strategy — clock-injected pure core so heavy compute is testable off the UI isolate.

References

• Flutter — Performance best practices
• Flutter — Performance profiling / UI performance
• Flutter — Concurrency and isolates / compute
• Flutter — Impeller rendering engine
• Flutter API — RepaintBoundary
• Flutter API — ResizeImage / cacheWidth
• Riverpod — using select to filter rebuilds