scroll_spy

Use when replacing the visibility_detector package with scroll_spy in a Flutter app, when migrating VisibilityDetector, VisibilityInfo, or VisibilityDetectorController code, or when a VisibilityDetector-based feed additionally needs a single stable primary item, per-item focus metrics, or scroll-performance improvements.

Use when scroll_spy misbehaves in a Flutter app and the cause is unknown: primaryId stays null, focusedIds stays empty, listeners or builders never fire, focus ignores jumpTo or programmatic scrolls, the highlighted item is offset under a pinned header or app bar, state resets on setState, nested scrollables interfere, or a widget test reads null focus state.

Use when adding the scroll_spy Flutter package to a screen or feature: autoplay video feeds, current-item tracking, reading-position or TOC highlighting, impression analytics, carousels or PageViews, photo grids, prefetching around the focused item, or wiring ScrollSpyScope, ScrollSpyItem, and ScrollSpyController for the first time, including widget tests for that integration. Not for scrolling work unrelated to focus or visibility tracking (saving/restoring scroll offsets, scroll physics, scroll-to-index).

Use when upgrading a Flutter project from scroll_spy 0.1.x or 0.2.x to 1.x, when a build breaks after a scroll_spy upgrade with unresolved names such as ScrollSpyRegistry, ScrollSpyGeometry, ScrollSpySelection, ScrollSpyDiff, or commitFrame, or when estimating how much work the 0.x to 1.x upgrade needs.

Use when a Flutter screen whose code uses scroll_spy (ScrollSpyScope, ScrollSpyItem, ScrollSpyController) shows jank, dropped frames, high CPU, or rebuild storms, or when choosing between ScrollSpyItem, ScrollSpyItemLite, focus builders, listeners, and snapshot listening in large scroll_spy feeds. Not for general Flutter list or image scrolling performance where scroll_spy is not involved.

Use when scroll_spy selects the right things but behaves badly over time: the primary item flickers or alternates between two items, switches too eagerly or too sluggishly, stutters at card boundaries in autoplay, goes null between items or during fast scrolls, sticks to an old item too long, or updates at the wrong moments (mid-drag versus after settling).