Lists, Grids & Scrolling — Flutter Course

What you'll learn

Render large collections efficiently with lazy builders, stable identity, pagination, refreshing, and resilient list states. The lesson turns the APIs into a repeatable engineering workflow instead of a collection of isolated snippets.

By the end of this lesson, you'll be able to:

Apply Lazy lists and grids in a production-shaped Flutter feature
Apply Scroll controllers in a production-shaped Flutter feature
Apply Stable keys in a production-shaped Flutter feature
Apply Pagination in a production-shaped Flutter feature

Core mental model

Connect each API to the decision it supports. Flutter code stays maintainable when state, ownership, lifecycle, and platform boundaries are explicit.

Concept	What it means	Decision rule
Builder	Creates visible collection children on demand	Use for long or unbounded lists rather than materializing every widget
Stable key	Connects a rendered child to domain identity	Key reorderable or stateful items by a stable record identifier
Pagination threshold	Loading begins shortly before the current end	Guard against duplicate loads and preserve retry state

Professional workflow

Work in small vertical slices and keep behavior observable from the first iteration.

Define the lazy paginated lesson list boundary: user goal, inputs, visible states, ownership, and expected failures.
Build the smallest working vertical slice with typed data and explicit dependencies.
Represent loading, empty, success, and failure behavior where the feature can encounter them.
Verify logic away from the UI, then exercise the rendered behavior at its public boundary.
Inspect lifecycle, accessibility, performance, security, and platform behavior before widening the feature.
Refactor only after behavior is protected by repeatable evidence.

Protect the frame

Keep build methods predictable, move side effects to explicit owners, and measure before introducing caches, isolates, or architectural layers.

Guided Flutter lab

Build a focused lazy paginated lesson list slice

This compact example keeps the important ownership and data-flow decisions visible so the behavior is easy to extend and test.

lib/lesson_list.dart

class LessonList extends StatelessWidget {
  const LessonList({super.key, required this.lessons, required this.loadingMore});
  final List<({String id, String title})> lessons;
  final bool loadingMore;

  @override
  Widget build(BuildContext context) => ListView.separated(
    itemCount: lessons.length + (loadingMore ? 1 : 0),
    separatorBuilder: (_, __) => const Divider(height: 1),
    itemBuilder: (context, index) {
      if (index == lessons.length) {
        return const Padding(padding: EdgeInsets.all(24), child: Center(child: CircularProgressIndicator()));
      }
      final lesson = lessons[index];
      return ListTile(key: ValueKey(lesson.id), title: Text(lesson.title));
    },
  );
}

Production practice

Contract

Define the lazy paginated lesson list inputs, outputs, owner, lifecycle, visible states, and platform assumptions before selecting APIs or packages.

Verification

Protect pure rules with unit tests and the rendered public contract with widget or integration evidence; include one unavailable or failure case.

Operations

Keep dependencies replaceable, log actionable context without user secrets, and measure user-visible behavior before optimizing.

Common failure mode

Using shrinkWrap inside nested scrollables forces extra measurement and can destroy the lazy performance the builder was meant to provide.

Independent workshop

Extend the guided lab into a review-ready lazy paginated lesson list feature that fits the running course portfolio app.

Your finished workshop must include:

Lazy lists and grids
Scroll controllers
Stable keys
Pagination
Refresh
Automated verification and a short design note

Definition of done

Demonstrate the happy path, an empty or unavailable state, and at least one failure path. Add an automated check and a short note explaining one design decision.

Recap & quick check

Key takeaways

Builder: Use for long or unbounded lists rather than materializing every widget
Stable key: Key reorderable or stateful items by a stable record identifier
Pagination threshold: Guard against duplicate loads and preserve retry state

Quick check

1. Which rule best applies to Builder?

2. Which rule best applies to Stable key?

3. Which rule best applies to Pagination threshold?

Next: Project: Complete Local App