Lists and Scrolling
Decide whether to act
| Situation | Action |
|---|---|
| Dataset can grow large or is dynamic (histories, feeds, search results, activity logs) | Use lazy construction |
| Small fixed UI list (settings rows, 5 tabs) | Leave it |
Already .builder |
Check extents and item cost instead |
Eager pattern to remove
ListView(children: items.map((item) => ItemTile(item)).toList())
This builds every item up front. Replace with:
ListView.builder(
itemCount: items.length,
itemBuilder: (context, i) => ItemTile(items[i]),
)
Equivalent lazy APIs: GridView.builder, SliverList.builder, SliverGrid.builder inside CustomScrollView. A Column of mapped items inside SingleChildScrollView is the same eager problem.
Known item sizes
If items share a predictable main-axis size, assess:
itemExtent: fixed extent for every itemprototypeItem: sizes all items like a sample widgetitemExtentBuilder: per-index extent when sizes vary but are computable
These let the sliver skip measuring each child. Do not apply when item height depends on content (wrapping text) unless it can be computed exactly; a wrong extent clips or misaligns content.
Intrinsic passes
Flutter aims for one layout pass. Sizing every cell from the biggest or smallest one (a uniform grid of Cards, IntrinsicHeight, IntrinsicWidth) needs a second, intrinsic pass over all cells, not just the visible ones.
- Detect: turn on "Track layouts" in DevTools (off by default) and look for timeline events labelled
<runtimeType> intrinsics. - Fix: give cells a fixed size up front, or pick one anchor cell and size the others from it (this needs a custom
RenderObject; only do it when the profile justifies it).
Item cost
- Keep
itemBuildercheap; no sorting, formatting setup, or aggregation inside it. Prepare item view-models upstream. - Use stable keys when items reorder or are removed, so state follows the right row.
- Group headers (by date) belong in prepared data or a sliver structure, not recomputed per frame.
- Images in rows: see flutter-perf-images-and-assets.
Very large data
If the client receives thousands of records only to show a page, check for existing backend pagination before adding client tricks. See flutter-perf-derived-state section "Client vs backend".
Verify
Profile-mode scroll through a representative large list (hundreds to several thousand rows); compare jank frames before/after. See flutter-perf-profiling-and-validation.
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.