# Flutter Perf Lists And Scrolling

> Use for janky scroll, slow first paint of long lists, or thousands of widgets built at once. Improves scrolling and list performance in Flutter: replaces eager ListView(children: data.map(...).toList()) with ListView.builder, GridView.builder or sliver builders for large item histories, and evaluates itemExtent, prototypeItem and itemExtentBuilder to cut layout work. Do not use for small fixed lists, and not for per-item rebuild scope (flutter-perf-build- and-rebuild).

- Skill: `kinwisenz-devops/flutter-perf-lists-and-scrolling` (Agent Skill)
- Install (CLI): `npx get-skill add kinwisenz-devops/flutter-perf-lists-and-scrolling`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kinwisenz-devops/flutter-perf-lists-and-scrolling/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: KinwiseNZ-DevOps (https://skillmd.com/u/kinwisenz-devops)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/kinwisenz-devops/flutter-perf-lists-and-scrolling

---


# 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

```dart
ListView(children: items.map((item) => ItemTile(item)).toList())
```

This builds every item up front. Replace with:

```dart
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 item
- `prototypeItem`: sizes all items like a sample widget
- `itemExtentBuilder`: 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 `Card`s, `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 `itemBuilder` cheap; 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](../flutter-perf-images-and-assets/SKILL.md).

## 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](../flutter-perf-derived-state/SKILL.md) 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](../flutter-perf-profiling-and-validation/SKILL.md).

## 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.

