Custom Painting and RenderObjects
Painting code runs on every repaint. Act only where the profile shows the painter or render object is the cost.
Gate
Profile mode, DevTools Performance view. Is the slow work in paint or layout of the custom widget? Use "Track layouts" and the repaint tooling to confirm it repaints more often than it changes. If the painter is cheap or rarely repaints, record it as acceptable.
1. Repaint only when the drawing changes
shouldRepaintmust compare the fields the drawing uses. Returningtruealways repaints on every parent rebuild. Returningfalsealways can show stale drawing; compare the real inputs.- For animation, pass the
Animationor otherListenableas the painter'srepaintargument. The canvas repaints on each tick without rebuilding widgets, instead ofsetStateon every frame. - Keep a changing painter below the large subtree, so the parent does not rebuild with it. Rebuild scope: flutter-perf-build-and-rebuild.
RepaintBoundaryaround aCustomPainthelps only where repaint tracing shows the surrounding content repainting needlessly; it is not a default. See flutter-perf-rendering-effects.CustomPainthasisComplexandwillChangehints for the raster cache. Evaluate them only for a painter that is expensive and either static or constantly changing, and confirm in the profile.
2. Work inside paint()
| Pattern | Action |
|---|---|
Paint, Path, TextPainter, gradient or shader objects created on every paint |
Create them once (field or painter constructor) and rebuild only when their inputs change |
TextPainter.layout on every paint for unchanged text |
Cache the laid-out painter; dispose it with its owner |
Complex Path rebuilt each frame from unchanged data |
Build once per data change |
| Drawing thousands of items when few are visible | Skip items outside the visible area (the canvas can report its current clip bounds) |
| Static background redrawn with every moving element | Draw it in a separate painter behind a RepaintBoundary, or record it once into a Picture and replay it, if profiling shows benefit |
saveLayer, clipPath, large blur in the painter |
Treat as in flutter-perf-rendering-effects |
Keep drawing results visually identical.
3. Fragment shaders
Load a FragmentProgram once and reuse it; do not load it from the asset bundle on every paint or build. Shaders are declared under flutter: shaders: in pubspec.yaml. Test on real devices; behaviour can differ by GPU and rendering engine, and the rendering engine changes between Flutter versions, so check the current Flutter docs before claiming shader warm-up or compile behaviour.
4. Custom RenderObject
Write one only when widgets cannot express the layout and the profile justifies it.
- Setters call
markNeedsLayout()ormarkNeedsPaint()only when the value actually changed, and choose the smaller one that is correct. - Implement
updateRenderObjectso a rebuild copies changed properties instead of replacing the object. - Layout the children once per pass; pass the tightest correct constraints.
- Do not implement intrinsic or dry-layout methods unless a parent needs them; see the intrinsic pass note in flutter-perf-lists-and-scrolling.
Verify
Compare paint time and repaint count for the screen before and after, in profile mode on a physical device, plus a visual comparison. Method: flutter-perf-profiling-and-validation.
Hard rules
- Act only on what the user asked. Before answering or changing anything, open the relevant files and check what is already done; report only what you checked, never guess, and do not redo finished work. Reason: guesses and repeated work waste the user's credit.