A list that stutters while scrolling, an animation that drops frames the moment a notification badge updates: the symptom is always the same vague "it's laggy," but the cause is rarely a single thing. Flutter has a well-defined rendering pipeline, and most jank issues get solved by understanding exactly where in that pipeline time is being lost, rather than sprinkling const everywhere and hoping it helps.
Understanding the frame budget
Flutter targets 60 or 120 frames per second depending on the display, which leaves 16.6 ms or 8.3 ms respectively to produce a complete frame. That budget splits into two main phases, both visible in DevTools: the UI thread (build, layout, paint, scene construction) and the raster thread (rasterizing layers into pixels via Skia or Impeller). Jank can come from either side, and the fix is different depending on which one it is.
Diagnosing with the Performance Overlay and DevTools
The first move is enabling the performance overlay:
MaterialApp(
showPerformanceOverlay: true,
home: const HomePage(),
)
The two graphs show UI time and raster time per frame respectively. A red bar on the top graph points to a UI-thread problem (too much work in build(), too many widgets rebuilding); a red bar on the bottom graph points to a rasterization problem (expensive effects, saveLayer, blur, shadows).
To go further, DevTools' Performance tab lets you record a timeline and enable "Track widget rebuilds," which shows exactly which widgets rebuild on each frame and how many times. That's the only reliable way to confirm a widget is actually rebuilding more than it should, instead of assuming it from reading the code.
Cause #1: rebuilds propagating too wide
The classic trap is calling setState() on an ancestor that sits too high in the tree. By default, setState() marks the owning State for rebuild along with its entire build() subtree, even if only a single line of text changed.
class ProductPage extends StatefulWidget {
const ProductPage({super.key});
@override
State<ProductPage> createState() => _ProductPageState();
}
class _ProductPageState extends State<ProductPage> {
int _likes = 0;
@override
Widget build(BuildContext context) {
return Column(
children: [
ExpensiveProductCarousel(), // rebuilds on every like
LikeButton(
likes: _likes,
onTap: () => setState(() => _likes++),
),
],
);
}
}
Every tap on "like" replays the entire ProductPage.build(), including ExpensiveProductCarousel, which has nothing to do with the like counter.
The fix: push state down and isolate with dedicated widgets
The fix isn't caching, it's shrinking the scope of the setState() call. Extracting the part that actually changes into its own StatefulWidget limits the rebuild to that subtree:
class LikeButton extends StatefulWidget {
const LikeButton({super.key});
@override
State<LikeButton> createState() => _LikeButtonState();
}
class _LikeButtonState extends State<LikeButton> {
int _likes = 0;
@override
Widget build(BuildContext context) {
return IconButton(
icon: Text('$_likes'),
onPressed: () => setState(() => _likes++),
);
}
}
Since ExpensiveProductCarousel is no longer in the same State, it no longer rebuilds at all when liking.
Cause #2: confusing "build" with "expensive re-render"
A widget rebuild isn't necessarily expensive on its own: Flutter separates reconstructing the Widget object (a lightweight operation on immutable configuration) from the actual layout and paint work done on the underlying Element/RenderObject. The real cost shows up when build() itself contains heavy work: sorting a list, formatting computations, a synchronous query, or allocating large objects on every frame.
// Bad: recomputed on every frame, even without a data change
@override
Widget build(BuildContext context) {
final sorted = widget.items.sortedBy((i) => i.price); // expensive if items is long
return ListView(children: sorted.map(ItemTile.new).toList());
}
The fix is to move that computation out of build() and memoize it (through a provider, a late final recomputed only when the source changes, or a dedicated ValueNotifier), not to "optimize" the sort itself.
Cause #3: ListView and const used the wrong way
For long lists, using ListView.builder instead of a ListView fed a fully pre-built widget list is essential: .builder only constructs the visible items (plus a small margin), while the non-lazy version builds the entire widget tree at once, even off-screen.
ListView.builder(
itemCount: items.length,
itemBuilder: (context, index) => ItemTile(item: items[index]),
)
The const constructor on a widget only helps if every one of its parameters is itself constant at construction time. Marking a widget const while it receives an inline callback (onTap: () => doSomething()) changes nothing: that callback is a fresh closure instance on every build, so the parent widget isn't actually constant. The real benefit of const shows up mainly on static subtrees (fixed icons, fixed text, separators) that Flutter can then skip entirely when the parent rebuilds.
Cause #4: the hidden cost of the raster thread
When the top (UI) graph is clean but the bottom (raster) one spikes, the problem is typically expensive-to-rasterize visual effects: BoxShadow, BackdropFilter (blur), ClipRRect over large areas, opacity applied to a complex subtree through Opacity instead of directly on the colors. Each of these widgets can force a saveLayer at the rendering engine level, an operation that has nothing to do with the number of Dart rebuilds.
// Expensive: forces a layer composition on every animated frame
Opacity(
opacity: _animation.value,
child: HeavyWidgetTree(),
)
// Better: let the widget handle its own opacity when possible
FadeTransition(
opacity: _animation,
child: HeavyWidgetTree(),
)
FadeTransition avoids rebuilding HeavyWidgetTree on every animation tick, unlike Opacity combined with a poorly placed AnimatedBuilder.
The limits of widget-level optimization
All of these fixes assume the problem lives in the widget tree. If jank only shows up on low-end devices or in release mode, but never in debug on a powerful device, profile strictly in --profile mode (never debug, which carries its own unrepresentative overhead) and check whether the bottleneck is elsewhere: heavy JSON deserialization on the main thread, decoding images that weren't resized beforehand, or blocking work that should be offloaded to an Isolate through compute().
Isolating raster cost with RepaintBoundary
When a widget has a real, stable paint cost (a complex chart, a filtered image), the problem usually isn't that it repaints too often, but that its repaint drags its neighbors along within the same compositing layer. RepaintBoundary forces Flutter to isolate that widget in its own layer: its repaint no longer triggers a repaint of the rest of the tree, at the cost of an extra compositing layer for the rendering engine to manage.
RepaintBoundary(
child: ComplexChart(data: liveData), // repaints on its own, isolated from the rest
)
It's a memory-for-CPU tradeoff: every RepaintBoundary adds a dedicated GPU texture. Overusing it across dozens of small static widgets can hurt video memory more than it saves in paint time; DevTools' "Highlight repaints" overlay (the blinking paintbrush icon) shows exactly which areas of the screen actually repaint on each frame, letting you place RepaintBoundary only where an isolated repaint is confirmed to be expensive.
Adding custom markers to the timeline
For business-logic operations that don't map to any standard pipeline phase (parsing a network response, computing a route, decoding a local file), the dart:developer API lets you add custom events visible directly in the DevTools timeline, right next to build and raster.
import 'dart:developer' as developer;
Future<void> loadDashboardData() async {
developer.Timeline.startSync('parse-dashboard-json');
final result = jsonDecode(rawResponse);
developer.Timeline.finishSync();
// ...
}
This instrumentation shows, directly overlaid on the UI/raster bars, whether a one-off jank coincides with a specific business-logic operation, instead of resting on the generic hypothesis that "the widget tree is just too heavy."
Takeaway: Flutter jank should be diagnosed, not guessed at. Start with the performance overlay to know whether the cost sits on the UI or raster side, then use "Track widget rebuilds" to confirm exactly which widget rebuilds and why, before choosing between shrinking the setState scope, moving a computation out of build(), or swapping a visual-effect widget for a cheaper-to-rasterize alternative.
