Lists with ListView

Why ListView.builder?

Most apps are lists: chats, products, transactions, notifications. A list may have thousands of items. Building every item at once wastes memory and time, especially on budget phones. ListView.builder builds only the items currently visible (plus a few around them) and builds new ones as the user scrolls. It is called lazy building.

class Txn {
  const Txn(this.title, this.amount);
  final String title;
  final int amount;
}

class StatementList extends StatelessWidget {
  const StatementList({super.key, required this.txns});
  final List<Txn> txns;

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      itemCount: txns.length,
      itemBuilder: (context, index) {
        final t = txns[index];
        return ListTile(
          leading: Icon(t.amount < 0 ? Icons.arrow_upward : Icons.arrow_downward),
          title: Text(t.title),
          trailing: Text('Rs ${t.amount.abs()}'),
        );
      },
    );
  }
}

itemCount tells the builder how many items exist, so the list knows where it ends and how long the scrollbar should be. Leave it out only for truly endless lists, and then return null from itemBuilder when there are no more items. Each call to itemBuilder should be cheap: read the item, build a small widget, nothing more.

Lists usually get their data from state (a List in a StatefulWidget, a Provider or a Bloc). When that list changes and the widget rebuilds, ListView.builder shows the new items; you never add or remove rows by hand.

The three ListView constructors

ListView.separated(
  itemCount: contacts.length,
  separatorBuilder: (context, index) => const Divider(height: 1),
  itemBuilder: (context, index) => ListTile(title: Text(contacts[index])),
)

ListTile

ListTile is a Material row layout with slots: leading (an icon or avatar), title, subtitle, trailing (an icon, a switch or text) and onTap. It handles padding, height and accessibility for you, so most list rows can start as a ListTile.

Swipe and pull

RefreshIndicator(
  onRefresh: () async => await reloadOrders(),       // must return a Future
  child: ListView.builder(
    itemCount: orders.length,
    itemBuilder: (context, i) => Dismissible(
      key: ValueKey(orders[i].id),                    // a unique, stable key per item
      onDismissed: (_) => removeOrder(orders[i].id),
      background: Container(color: Colors.red),
      child: ListTile(title: Text(orders[i].title)),
    ),
  ),
)

A key is a stable identity for a widget. When items move or are removed, keys let Flutter match old and new items correctly, so a swipe or animation affects the right row. Use something unique from your data, such as an id, with ValueKey.

Common mistakes

• Using ListView(children: list.map(...).toList()) for hundreds of items: slow. Use ListView.builder.
• Putting a ListView inside a Column without Expanded: unbounded height error (module 5).
• Using the index as the Dismissible key: after a delete, indexes shift and the wrong item is affected. Use a unique id.
• Doing heavy work (date formatting, parsing) inside itemBuilder for every item: prepare data beforehand.