Flutter Render Objects

Flutter render objects

This skill is the renderobjects.com guides, API pages and examples by Matt Carroll (https://renderobjects.com/), with every API claim checked against api.flutter.dev and the Flutter framework source. The site states no Flutter version, and some of its code does not compile or contradicts the framework; wherever that happens the files give the official form first and then one line saying what renderobjects.com has. What decides most outcomes: the element tree owns the children and the render tree only reacts, every property setter marks exactly the right thing dirty, and whatever a render object reports without laying out (dry size, baselines, intrinsics) matches what its real layout produces. App-level frame budget and the advice to avoid intrinsic passes are in flutter PERFORMANCE.md; tap targets, the Semantics widget and screen-reader checks are in flutter ACCESSIBILITY.md; everything else about building the app is flutter SKILL.md.

Apply only the routes and checks for the selected job. Read a linked skill's named file from its installed folder when available, or from the linked source. Report an unavailable required reference instead of inventing it. [skill-authoring, DISTRIBUTION.md#composing-skills]

The three trees

• Widget: immutable, lightweight configuration, "recreated on every rebuild" (renderobjects); "the blueprint" (ApparenceKit).
• Element: "the running instance of your widget tree". Elements persist across rebuilds and are reused when the new widget has "the same type and key in the same position"; on a rebuild an element usually just updates its render object's properties from the new widget's fields. Without elements, every rebuild would mean "recreating render objects from scratch, losing layout caches, scroll positions, and animation state". renderobjects
• Render object: does layout, paint, hit tests and semantics. "Not every widget corresponds to a render object ... but every render object is owned by some element above it." renderobjects
• A widget instance can be placed zero or more times; each placement inflates an element. Component elements (Builder, every StatelessWidget) own no render object, so element to render object is not one to one. Widget. P2 correction: the renderobjects introduction and the old line here described widget to element as one to one without distinguishing a placement from a reusable widget instance.
• "The element tree is authoritative ... The render tree is reactive." Render children change only through RenderObjectElement.insertRenderObjectChild, moveRenderObjectChild and removeRenderObjectChild, each given a render object and a slot: "an opaque identifier that tells the parent element where in the render tree's child structure this render object belongs" (a list index, a named slot, an index plus a previous sibling). "The slot is the bridge between the two trees." renderobjects Official: a slot is "an identifier whose meaning is private to this RenderObjectElement node", set by updateChild and changed with updateSlotForChild (https://api.flutter.dev/flutter/widgets/RenderObjectElement-class.html).

When to write a render object

• Custom render objects are "for advanced drawing or unique layout needs, not for everyday UI pieces like buttons or text fields"; they "control layout, handle gestures, and paint exactly what you need directly". ApparenceKit
• A UI is "a good candidate for a custom render object" when it has child widgets, the "layout of child size and position is nuanced", or "only visible children should be built, therefore build happens during layout" (long or unbounded lists, scrollable tables and spreadsheets, an infinite canvas). renderobjects
• "even simple widgets can sometimes benefit from a custom render object": a thumbnail with a circle cut out for an "x" button "could be built with a widget tree", but "that widget tree would be rather confusing". renderobjects
• A full interactive control can be "nothing but a custom RenderBox: no nested widgets, just direct Canvas painting, layout, hit-testing, and gesture handling"; the same approach suits charts such as a candlestick stock chart. renderobjects
• On the performance side, Flutter's guidance that the ideal build is "a single widget, and that widget would be a RenderObjectWidget", and the custom "anchor" cell that avoids an intrinsic pass, are in flutter PERFORMANCE.md.

Choosing a child model

From the "When ... fits" sections of the children guides (list, slotted, custom, virtualized); code for each is in CHILD-MODELS.md.

The rules

1. Never add or remove render children yourself. The element decides; the render tree changes only through insertRenderObjectChild, moveRenderObjectChild and removeRenderObjectChild with a slot (renderobjects). A custom element skips forgotten children in visitChildren and clears them once per update, or GlobalKey reparenting loses state (CHILD-MODELS.md).
2. Every property setter returns early on an equal value, then marks the right thing dirty: markNeedsLayout() when layout changes (it implies a repaint), markNeedsPaint() when only appearance changes, never both. A missing markNeedsLayout() is "the single most common bug in custom render objects" (renderobjects, renderobjects).
3. Read a child's size only after child.layout(..., parentUsesSize: true), and always set your own size inside the incoming constraints with constraints.constrain(...) or its relatives (LAYOUT.md).
4. Forward every non-child field in updateRenderObject, and read inherited values such as Directionality.of(context) in the widget and push them down; render objects never see BuildContext (renderobjects, renderobjects).
5. What you report without laying out must match your real layout, and children are asked through the public getters: getDryLayout, getDryBaseline, getDistanceToActualBaseline, getMinIntrinsicWidth and the rest, never compute* on a child and never child.layout inside them (https://api.flutter.dev/flutter/rendering/RenderBox/computeDryLayout.html, LAYOUT.md).
6. Parent data: guard setupParentData with is!, extend ContainerBoxParentData<RenderBox> with the container mixins (BoxParentData without them), and have applyParentData mark the parent only when a value changed (https://api.flutter.dev/flutter/rendering/ContainerRenderObjectMixin-mixin.html, PARENT-DATA.md).
7. Mutate a child list during layout only inside invokeLayoutCallback, with the building inside BuildOwner.buildScope; use RenderObjectWithLayoutCallbackMixin for a builder that runs from layout (https://api.flutter.dev/flutter/widgets/RenderObjectElement-class.html, https://api.flutter.dev/flutter/rendering/RenderObjectWithLayoutCallbackMixin-mixin.html).
8. Where renderobjects.com and api.flutter.dev disagree, follow api.flutter.dev. Each file marks the disagreements; the site's snippets are not runnable as a whole (helpers are elided).

Prove it

flutter analyze is clean (no mixin type-bound errors, no BoxParentData.nextSibling, no shadowed IndexedWidgetBuilder); every setter has the equality early return and the matching markNeeds* call; a widget test changes each widget field and sees the render object update; the widget inside IntrinsicHeight and inside a baseline-aligned Row throws no dry-layout assertion; a reorderable child list keeps child state across a reorder, and a custom element keeps a GlobalKey child's state when it moves in and out; and every file's own Prove it checks pass for the parts you touched.