# Flutter Perf Custom Painting

> Use when DevTools shows a CustomPaint or custom RenderObject taking long paint or layout time, or a chart, canvas or drawing screen drops frames. Reviews Flutter custom painting cost: shouldRepaint returning true, repainting through setState instead of a repaint listenable, Paint, Path and TextPainter objects rebuilt on every paint, drawing offscreen content, static drawing redrawn each frame, fragment shader loading, and RenderObject setters that mark layout or paint when nothing changed. Do not use for Opacity, blur or clipping widgets (flutter-perf-rendering-effects) or for rebuild scope.

- Skill: `kinwisenz-devops/flutter-perf-custom-painting` (Agent Skill)
- Install (CLI): `npx get-skill add kinwisenz-devops/flutter-perf-custom-painting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kinwisenz-devops/flutter-perf-custom-painting/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: KinwiseNZ-DevOps (https://skillmd.com/u/kinwisenz-devops)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/kinwisenz-devops/flutter-perf-custom-painting

---


# 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

- `shouldRepaint` must compare the fields the drawing uses. Returning `true` always repaints on every parent rebuild. Returning `false` always can show stale drawing; compare the real inputs.
- For animation, pass the `Animation` or other `Listenable` as the painter's `repaint` argument. The canvas repaints on each tick without rebuilding widgets, instead of `setState` on 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](../flutter-perf-build-and-rebuild/SKILL.md).
- `RepaintBoundary` around a `CustomPaint` helps only where repaint tracing shows the surrounding content repainting needlessly; it is not a default. See [flutter-perf-rendering-effects](../flutter-perf-rendering-effects/SKILL.md).
- `CustomPaint` has `isComplex` and `willChange` hints 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](../flutter-perf-rendering-effects/SKILL.md) |

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()` or `markNeedsPaint()` only when the value actually changed, and choose the smaller one that is correct.
- Implement `updateRenderObject` so 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](../flutter-perf-lists-and-scrolling/SKILL.md).

## 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](../flutter-perf-profiling-and-validation/SKILL.md).

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

