flutter-performance skill by zakariaf

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

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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

.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

Lazy lists and sized images

Heavy work off the UI isolate

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

flutter run --profile on a physical floor device.
DevTools -> Performance; record while reproducing the jank.
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.
Use "Track widget rebuilds" to find widgets rebuilding too often.
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.

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