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.
```
AnimationController
```
s, gesture recognizers, stream subscriptions, timers,
```
TextEditingController
```
s, 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:

dart

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

dart

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

dart

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

dart

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

```
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
```
autoDispose
```
d; 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.

flutter-performance

NPX Install

Tags

SKILL.md Content

Flutter Performance

Non-negotiable rules

Narrow the rebuild scope

Keep expensive children out of the animation loop

Lazy lists and sized images

Heavy work off the UI isolate

Custom painting

Profiling workflow

Anti-patterns

Definition of done

Related skills

References