Flutter ListView Viewport Recycling Gotchas

Core Problem

ListView, CustomScrollView, and GridView are viewport-based — they only keep widgets that are within or near the visible area mounted in the widget tree. Widgets scrolled out of view are disposed and their State is destroyed. When the parent calls setState, disposed children are recreated from scratch (new State, initState called) rather than updated (didUpdateWidget called).

This causes several classes of bugs:

Bug Pattern 1: didUpdateWidget Never Called

Symptom: A StatefulWidget inside a ListView should react to prop changes via didUpdateWidget, but logcat shows didUpdateWidget is never triggered.

Root cause: The widget was scrolled out of view → disposed → recreated as a new instance after setState.

Fix: Duplicate prop-change logic in both initState and didUpdateWidget: