RenderObject: Below Widgets

This is Part 6 — the final content part of the Flutter Internals series (the question bank is next). We've worked down through widgets, elements, keys, context, lifecycle, and slivers. Now we reach the bottom: the RenderObject — the third tree from Part 1, where layout is computed, pixels are painted, and taps are tested.

Most developers never touch this layer directly, and that's fine — Flutter's widgets cover almost everything. But understanding it is what separates "I arrange widgets" from "I understand how Flutter decides every size and position on screen." And occasionally you do drop here: a custom layout no Row/Stack/Flex can express, or painting that needs full control. Let's go below widgets.

The capstone of the series — builds on all prior parts, especially Part 1 and layouts/constraints. Flutter 3.38 / Dart 3.12.

Where RenderObjects sit

Recall the three trees (Part 1): Widgets (config) → Elements (instances) → RenderObjects (layout + paint). Not every widget has a render object — composition widgets (StatelessWidgets, Padding, Center) build other widgets, but eventually you reach widgets backed by a real RenderObject that does physical work.

A RenderObject is responsible for three jobs: layout (compute its own size and place its children), paint (draw to the canvas), and hit testing (decide if a tap at a point hits it). The most common base class is RenderBox — a render object in the familiar 2D cartesian (width × height) model. (Slivers from Part 5 use RenderSliver instead.)

The layout protocol: the single most important idea

Flutter's layout is famously fast because it's a single-pass algorithm with one rule you can recite in your sleep:

Constraints go down. Sizes go up. The parent sets position.

Analogy — the room negotiation. A parent tells each child: "You may be anywhere from this small to this big" (a BoxConstraints — min/max width and height). The child picks its own size within those limits and reports it back up. Then the parent decides where to place the child (its offset). The child never chooses its own position; the parent never chooses the child's size.

// BoxConstraints flowing DOWN:
BoxConstraints(minWidth: 0, maxWidth: 300, minHeight: 0, maxHeight: 600)

// The child's performLayout picks a Size within them and reports UP:
size = Size(300, 80);

// The PARENT then sets the child's position via parentData (offset).

This is why a Container() with no constraints can be huge or tiny depending on its parent, and why "unbounded constraints" errors happen (a parent offering maxHeight: infinity, like a Column, to a child that wants to fill it, like a ListView). Every layout puzzle in Flutter is this protocol playing out. (Constraints deep-dive.)

performLayout — the heart

A RenderBox implements performLayout: read the incoming constraints, lay out children (passing each its constraints), set their positions, and set its own size.

@override
void performLayout() {
  final BoxConstraints constraints = this.constraints; // came DOWN from parent
  // Lay out the child with constraints we choose:
  child.layout(constraints.loosen(), parentUsesSize: true);
  // Place the child (we, the parent, decide position):
  (child.parentData as BoxParentData).offset = const Offset(8, 8);
  // Choose OUR size within our constraints, reported UP:
  size = constraints.constrain(Size(child.size.width + 16, child.size.height + 16));
}

parentUsesSize: true tells the framework our layout depends on the child's size (so the child relaying out forces us to relayout). Omit it when you don't read the child's size — an optimization that limits relayout propagation.

Painting

After layout, paint draws using a Canvas (via PaintingContext) at the offset the parent assigned:

@override
void paint(PaintingContext context, Offset offset) {
  final canvas = context.canvas;
  final paint = Paint()..color = color;
  canvas.drawRRect(
    RRect.fromRectAndRadius(offset & size, const Radius.circular(8)),
    paint,
  );
  // Paint children, offset by their position:
  context.paintChild(child, offset + (child.parentData as BoxParentData).offset);
}

Layout and paint are separate phases. Layout decides sizes/positions; paint draws. They're invalidated independently: markNeedsLayout (size/position changed) vs markNeedsPaint (only appearance changed). Changing just a color calls markNeedsPaint — no relayout — which is cheaper. This is the same in-place update from Part 1: the render object is reused, just re-painted.

Hit testing

When you tap, Flutter walks the render tree asking each object "is this point inside you?" via hitTest, building the list of render objects under the pointer (which then dispatch the event). A RenderBox hit-tests against its size; custom render objects can override it for non-rectangular shapes.

@override
bool hitTestSelf(Offset position) => true; // the whole box is tappable

How a widget creates a RenderObject

This connects straight back to Part 1's reconciliation. Widgets that own a render object extend a RenderObjectWidget and implement two methods the RenderObjectElement calls:

class ColoredSquare extends LeafRenderObjectWidget {
  const ColoredSquare(this.color, {super.key});
  final Color color;

  @override
  RenderObject createRenderObject(BuildContext context) =>
      RenderColoredSquare(color); // called ONCE, when the element mounts

  @override
  void updateRenderObject(BuildContext context, RenderColoredSquare ro) {
    ro.color = color; // called on REBUILD when the element is reused (canUpdate)
  }
}

This is the payoff of the whole series. When canUpdate (Part 1) says "reuse the Element," the framework calls updateRenderObject, which mutates the existing render object in place (here, just sets color and internally markNeedsPaint). It does not create a new one. That's precisely why rebuilding widgets is cheap — the expensive render object persists and is tweaked. Type/key change → new Element → createRenderObject → a fresh render object.

Three base widget classes by child count:

| Base widget | Children | Example | | --- | --- | --- | | LeafRenderObjectWidget | none | Text (RenderParagraph), Image | | SingleChildRenderObjectWidget | one | Padding, Opacity, Align | | MultiChildRenderObjectWidget | many | Row/Column (RenderFlex), Stack |

When (and when not) to write one

Usually you don't. Reach for these before a custom RenderObject:

• CustomPaint — custom drawing (charts, signatures, gauges) without custom layout. Covers most "I need to draw something" cases.
• Existing layout widgets — Stack+Positioned, Flex, CustomMultiChildLayout, Flow solve most custom arrangement needs.

Write a custom RenderBox only when you need custom layout logic that none of those express — e.g. a bespoke flow that measures children and positions them by rules Wrap/Flex can't do.

class RenderColoredSquare extends RenderBox {
  RenderColoredSquare(this._color);
  Color _color;
  set color(Color v) {
    if (v == _color) return;
    _color = v;
    markNeedsPaint(); // appearance changed → repaint only, no relayout
  }

  @override
  void performLayout() {
    size = constraints.constrain(const Size(100, 100)); // pick size within constraints
  }

  @override
  void paint(PaintingContext context, Offset offset) {
    context.canvas.drawRect(offset & size, Paint()..color = _color);
  }

  @override
  bool hitTestSelf(Offset position) => true;
}

Notice the discipline: the color setter only markNeedsPaint() (not layout) because color doesn't affect size — minimizing work, the efficiency mindset at the lowest level.

Bonus: RepaintBoundary (a render-tree tool you'll actually use)

Even without writing render objects, one render-tree concept pays off constantly: RepaintBoundary isolates a subtree onto its own layer, so when it repaints (e.g. an animation) it doesn't force its neighbors to repaint, and vice versa.

RepaintBoundary(child: SpinningLogo()) // its repaints stay contained

When a small, frequently-animating widget sits among expensive static siblings, wrapping it in a RepaintBoundary can cut repaint cost dramatically — the render layer the animation dirties is its own. (This is a headline tip in Flutter performance guidance and connects to the efficiency rules.)

Practice Challenges

Challenge 1 — The mantra. State Flutter's layout rule in one line and say who decides size vs position.

Challenge 2 — Layout vs paint. Changing a widget's color, which invalidation runs — markNeedsLayout or markNeedsPaint — and why does it matter?

Challenge 3 — Reuse path. When a parent rebuilds and canUpdate reuses the Element, which RenderObject method runs, and what does it do?

Challenge 4 — Right tool. You need to draw a custom circular progress gauge. Custom RenderBox or CustomPaint? Why?

Challenge 5 — Contain the repaint. A tiny spinner animates next to a heavy static chart, and profiling shows the chart repainting every frame. What render-tree tool helps?

Questions to test yourself

Q1 (basic). What three jobs does a RenderObject do?

Q2 (basic). State the layout protocol and the data types involved.

Q3 (intermediate). Why are layout and paint invalidated separately?

Q4 (intermediate). How does updateRenderObject make widget rebuilds cheap?

Q5 (advanced). When should you write a custom RenderBox versus using CustomPaint or existing layout widgets?

Q6 (advanced). What does a RepaintBoundary do and when does it help performance?

Wrapping up

• RenderObjects (commonly RenderBox) do layout, paint, and hit testing — the bottom of the three trees.
• Layout is one pass: constraints go down (BoxConstraints), sizes go up (Size), the parent sets position — the source of every sizing puzzle and unbounded-constraint error.
• Layout and paint invalidate separately (markNeedsLayout vs markNeedsPaint); color-only changes just repaint.
• Widgets create render objects via createRenderObject (once) and updateRenderObject (on reuse, mutating in place) — the reason rebuilds are cheap (Part 1).
• Prefer CustomPaint/existing layout widgets; write a custom RenderBox only for bespoke layout. Use RepaintBoundary to isolate costly repaints.

That's the engine, top to bottom. Part 7 is the proving ground: a 100-question mastery bank — hints and solutions — plus 10 coding mini-exercises and a capstone that traces one interaction through every layer of Flutter you now understand.