Custom painters (CustomPaint) in Flutter - Deep Dive

Overview - Custom painters (CustomPaint)

What is it?

Custom painters in Flutter let you draw shapes, lines, and images directly on the screen. They give you full control over how things look by painting on a canvas. This is useful when built-in widgets can't create the exact design you want. You write code that tells Flutter how to draw each pixel.

Why it matters

Without custom painters, you would be limited to standard widgets and their styles. Custom painting lets you create unique graphics, animations, and visual effects that make your app stand out. It solves the problem of needing precise control over drawing beyond simple buttons or text.

Where it fits

Before learning custom painters, you should understand Flutter widgets and the basics of drawing with widgets like Container and Stack. After mastering custom painters, you can explore animations, gesture detection on custom drawings, and advanced graphics with shaders.

Mental Model

Core Idea

Custom painters let you draw directly on a canvas by writing code that controls every pixel's appearance.

Think of it like...

It's like having a blank canvas and paintbrush where you decide exactly what to paint, instead of using pre-made stickers or stamps.

┌───────────────┐
│ Flutter Widget│
│ Tree          │
│               │
│  ┌─────────┐  │
│  │Custom   │  │
│  │Paint    │  │
│  │Widget   │  │
│  └─────────┘  │
│       │       │
│       ▼       │
│  ┌─────────┐  │
│  │Canvas   │  │
│  │(Draw)   │  │
│  └─────────┘  │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

What is CustomPaint Widget

Concept: Introducing the CustomPaint widget that holds a painter to draw on the screen.

CustomPaint is a Flutter widget that provides a canvas to draw on. You give it a CustomPainter object that has a paint method. Flutter calls this method to draw your shapes or images. The CustomPaint widget fits into the widget tree like any other widget.

Result

You get a blank area on the screen where your painter can draw anything you want.

Understanding that CustomPaint is just a widget helps you see it fits naturally into Flutter's UI system.

2

Foundation

Basics of CustomPainter Class

Concept: Learning how to create a CustomPainter by overriding paint and shouldRepaint methods.

To create a custom painter, extend CustomPainter and override two methods: paint(Canvas canvas, Size size) and shouldRepaint(CustomPainter oldDelegate). The paint method is where you draw using the canvas. The shouldRepaint method tells Flutter when to redraw.

Result

You can write code inside paint to draw lines, shapes, or text on the canvas.

Knowing the paint method is your drawing playground is key to mastering custom painting.

3

Intermediate

Drawing Basic Shapes on Canvas

🤔Before reading on: do you think you can draw a circle with just one line of code or do you need multiple steps? Commit to your answer.

Concept: Using the Canvas API to draw shapes like circles, rectangles, and lines.

Inside the paint method, use canvas.drawCircle, canvas.drawRect, or canvas.drawLine with Paint objects to set colors and styles. For example, canvas.drawCircle(Offset(x, y), radius, paint) draws a circle at position (x,y).

Result

Your app shows the shapes you coded, rendered exactly where and how you specified.

Understanding the canvas API unlocks the ability to create any shape or design you imagine.

4

Intermediate

Controlling Paint Styles and Colors

🤔Before reading on: do you think Paint only controls color or can it also control stroke width and fill style? Commit to your answer.

Concept: Using the Paint class to customize how shapes are drawn, including color, stroke width, and fill.

Paint lets you set color, stroke width, stroke or fill style, and more. For example, paint.color = Colors.blue; paint.style = PaintingStyle.stroke; paint.strokeWidth = 4.0; changes how shapes appear. This controls whether shapes are filled or just outlines.

Result

Shapes appear with the colors and styles you set, making your drawings look polished and intentional.

Knowing how to customize Paint lets you create visually rich and varied graphics.

5

Intermediate

Handling Size and Position in Painting

🤔Before reading on: do you think the canvas size is fixed or does it depend on the widget size? Commit to your answer.

Concept: Using the Size parameter to adapt drawings to the widget's size and positioning elements correctly.

The paint method receives a Size object representing the widget's width and height. Use this to position shapes relative to the widget size, so your drawing scales well on different screen sizes. For example, draw a circle at Offset(size.width/2, size.height/2) to center it.

Result

Your drawings adjust to different screen sizes and orientations, looking good everywhere.

Using Size ensures your custom painting is responsive and flexible.

6

Advanced

Optimizing Repaints with shouldRepaint

🤔Before reading on: do you think shouldRepaint always returns true or can it return false sometimes? Commit to your answer.

Concept: Controlling when Flutter redraws your custom painter to improve performance.

The shouldRepaint method compares the old painter with the new one. Return true only if the drawing needs updating. Returning false avoids unnecessary redraws, saving CPU and battery. For example, compare properties that affect drawing and return true if they changed.

Result

Your app runs smoother because Flutter skips redrawing when nothing changed.

Knowing how to control repainting prevents performance issues in complex apps.

7

Expert

Combining CustomPaint with Animations

🤔Before reading on: do you think CustomPaint can animate drawings by itself or needs help from other widgets? Commit to your answer.

Concept: Using CustomPaint with animation controllers to create dynamic, moving graphics.

CustomPaint itself only draws static images. To animate, use an AnimationController and call setState or repaint the painter when the animation value changes. Pass the animation value to the painter to update the drawing each frame. This creates smooth animations like progress bars or waves.

Result

Your app shows animated custom drawings that respond to time or user input.

Understanding how to link CustomPaint with animations unlocks powerful, custom visual effects.

Under the Hood

Flutter's rendering engine calls the paint method of your CustomPainter whenever it needs to draw or redraw the widget. The Canvas object represents a low-level drawing surface where you can issue commands to draw shapes, text, or images. Flutter batches these commands and renders them efficiently on the screen. The shouldRepaint method helps Flutter decide if it can reuse the existing drawing or must call paint again.

Why designed this way?

CustomPaint was designed to give developers fine-grained control over drawing while fitting into Flutter's widget system. It separates the drawing logic (CustomPainter) from layout and composition (widgets). This design allows efficient redrawing and easy integration with Flutter's reactive model. Alternatives like direct pixel manipulation would be slower and harder to manage.

┌───────────────┐
│ Flutter Widget│
│ Tree          │
│               │
│  ┌─────────┐  │
│  │Custom   │  │
│  │Paint    │  │
│  │Widget   │  │
│  └─────────┘  │
│       │       │
│       ▼       │
│  ┌─────────┐  │
│  │Flutter  │  │
│  │Rendering│  │
│  │Engine   │  │
│  └─────────┘  │
│       │       │
│       ▼       │
│  ┌─────────┐  │
│  │Canvas   │  │
│  │Commands │  │
│  └─────────┘  │
│       │       │
│       ▼       │
│  ┌─────────┐  │
│  │GPU/CPU  │  │
│  │Draw     │  │
│  └─────────┘  │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does CustomPaint automatically animate your drawings without extra code? Commit yes or no.

Common Belief: CustomPaint automatically animates drawings when you change properties.

Reality: CustomPaint only draws static images; you must use animation controllers and trigger repaints to animate.

Why it matters: Believing this causes confusion and wasted time trying to animate without proper setup.

Quick: Can you use setState inside CustomPainter to update drawings? Commit yes or no.

Common Belief: You can call setState inside the CustomPainter class to update the UI.

Reality: CustomPainter is not a widget and cannot call setState; you must manage state outside and pass data in.

Why it matters: Misunderstanding this leads to errors and broken app logic.

Quick: Does returning false from shouldRepaint mean your drawing never updates? Commit yes or no.

Common Belief: If shouldRepaint returns false, the drawing will never update again.

Reality: Returning false means Flutter reuses the old painting; if your data changed, you must return true to update.

Why it matters: Returning false incorrectly causes stale visuals and bugs.

Quick: Is CustomPaint the only way to draw custom graphics in Flutter? Commit yes or no.

Common Belief: CustomPaint is the only way to draw custom graphics in Flutter.

Reality: Flutter also supports other methods like using widgets with decoration, ClipPath, or third-party libraries.

Why it matters: Knowing alternatives helps choose the best tool for the task.

Expert Zone

1

CustomPainter's paint method can be called many times per second; avoid heavy computations inside it to keep performance smooth.

2

The shouldRepaint method can compare complex state objects to decide repainting, but deep comparisons can hurt performance if not optimized.

3

You can combine multiple CustomPainters by layering CustomPaint widgets or using a CompositePainter pattern for modular drawing.

When NOT to use

Avoid CustomPaint for simple UI elements that standard widgets can handle, like buttons or text. For complex animations, consider using Flutter's built-in animation widgets or game engines like Flame. If you need pixel-level image manipulation, use specialized libraries instead.

Production Patterns

In production, CustomPaint is often used for charts, graphs, custom sliders, and game graphics. Developers separate drawing logic into reusable painters and optimize repaint triggers. Animations combine CustomPaint with AnimationController and Tween for smooth effects. Testing includes snapshot tests of painted output.

Connections

Canvas API (Web Graphics)

CustomPaint's Canvas API is similar to HTML5 Canvas drawing commands.

Understanding web canvas drawing helps grasp Flutter's painting commands since both use a procedural drawing model.

Declarative UI Frameworks

CustomPaint fits into Flutter's declarative widget tree but uses imperative drawing inside paint.

Knowing the mix of declarative layout and imperative drawing clarifies how Flutter balances flexibility and performance.

Traditional Painting and Art

CustomPaint mimics a painter's canvas where each stroke is deliberate and controlled.

Seeing CustomPaint as a digital painter's canvas helps appreciate the creative control it offers beyond standard UI.

Common Pitfalls

#1 Drawing heavy computations inside paint causing slow UI.

Wrong approach:

void paint(Canvas canvas, Size size) {
for (int i = 0; i < 10000; i++) {
// complex math here
canvas.drawCircle(Offset(i.toDouble(), i.toDouble()), 1, paint);
}
}

Correct approach:

Precompute data outside paint and store it; paint only draws precomputed results.

void paint(Canvas canvas, Size size) {
for (final point in precomputedPoints) {
canvas.drawCircle(point, 1, paint);
}
}

Root cause:

Misunderstanding that paint is called often and should be fast.

#2 Always returning true from shouldRepaint causing unnecessary redraws.

Wrong approach:

bool shouldRepaint(CustomPainter oldDelegate) => true;

Correct approach:

bool shouldRepaint(CustomPainter oldDelegate) {
return oldDelegate.someValue != this.someValue;
}

Root cause:

Not optimizing repaint logic leads to performance issues.

#3 Trying to call setState inside CustomPainter to update drawings.

Wrong approach:

class MyPainter extends CustomPainter {
void update() {
setState(() {}); // wrong
}
}

Correct approach:

Manage state in a StatefulWidget and pass updated data to CustomPainter.

class MyWidget extends StatefulWidget { ... }

class _MyWidgetState extends State {
double value = 0;
void update() {
setState(() { value += 1; });
}
}

Root cause:

Confusing widget lifecycle with painter class responsibilities.

Key Takeaways

CustomPaint is a Flutter widget that lets you draw anything by writing code in a CustomPainter.

The paint method is where you use a Canvas to draw shapes, lines, and images with full control.

The shouldRepaint method controls when Flutter redraws your painting to keep apps efficient.

CustomPaint works best combined with animations and state management for dynamic graphics.

Understanding CustomPaint bridges Flutter's declarative UI with low-level drawing power.