When and how would you use CustomPainter?

CustomPainter exposes a Canvas where you draw paths, text, images and gradients. The painter runs during paint, not build. Widgets are still better for interactive elements, semantics and layout. Custom painting is appropriate when the visual is inherently geometric or when many primitives would be wasteful as widgets.

class SparklinePainter extends CustomPainter {
  SparklinePainter(this.values);

  final List<double> values;

  @override
  void paint(Canvas canvas, Size size) {
    final paint = Paint()
      ..color = const Color(0xFF0F766E)
      ..strokeWidth = 2
      ..style = PaintingStyle.stroke;

    if (values.length < 2) return;

    final path = Path();
    for (var i = 0; i < values.length; i++) {
      final x = size.width * i / (values.length - 1);
      final y = size.height * (1 - values[i]);
      if (i == 0) {
        path.moveTo(x, y);
      } else {
        path.lineTo(x, y);
      }
    }
    canvas.drawPath(path, paint);
  }

  @override
  bool shouldRepaint(covariant SparklinePainter oldDelegate) {
    return !listEquals(oldDelegate.values, values);
  }
}

• Return true from shouldRepaint only when the drawing inputs changed
• Wrap the painter in RepaintBoundary when it animates independently
• Avoid saveLayer and large blurred shadows unless measured
• Reuse Paint and Path objects where possible, but not across different sizes incorrectly
• Provide semantics separately because canvas drawing is invisible to screen readers

Interaction and testing

Hit testing must be implemented manually through hitTest or by wrapping the painter in a gesture detector over known regions. Golden tests are effective for painter output. Keep the painter deterministic and avoid reading ambient state inside paint.