divine-mobile: Skill for Claude Code

Flutter PageView Scroll Position Preservation

Problem

Users scrolling through a PageView-based feed report that the scroll position resets or "snaps back" to a previous page, especially after state updates from providers (Riverpod, Provider, BLoC) or widget rebuilds.

Context / Trigger Conditions

• PageView with dynamic content from state management
• Provider/Riverpod state updates causing widget rebuilds
• Pagination that changes itemCount
• Orientation changes
• Tab switching and returning to the PageView

Root Cause

When Flutter rebuilds the widget tree (due to state changes), the PageView may lose its scroll position if:

1. No PageStorageKey is provided to persist state
2. The PageController is recreated during rebuilds
3. PageController.keepPage is set to false

Note: allowImplicitScrolling is for accessibility focus navigation, NOT scroll position preservation. A specific bug (#76569) involving TextField focus was fixed in Flutter.

Solution

1. Add PageStorageKey (PRIMARY FIX)

PageView.builder(
  // This key tells Flutter to persist scroll state across rebuilds
  key: const PageStorageKey<String>('my_page_view'),
  itemCount: videos.length,
  controller: _pageController,
  ...
)

2. Keep PageController in State (not build)

class _MyScreenState extends State<MyScreen> {
  // Create in initState, NOT in build()
  late PageController _pageController;

  @override
  void initState() {
    super.initState();
    _pageController = PageController();  // Created once
  }

  @override
  void dispose() {
    _pageController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    // Use the same controller instance
    return PageView.builder(
      controller: _pageController,
      ...
    );
  }
}

3. Ensure keepPage is true (default)

_pageController = PageController(
  keepPage: true,  // This is the default, but be explicit if needed
  initialPage: 0,
);