ScrollSpy Assistant

scroll_spy

Know what is visible. Choose one stable winner.

Viewport focus detection and stable primary item selection for Flutter scrollables, built for video autoplay feeds, analytics, reading position, carousels, and prefetching.

Want your AI agent to handle the integration? Install the official ScrollSpy Assistant plugin for Claude Code or OpenAI Codex. It teaches your agent exactly how to integrate, tune, and migrate this package.

Product guide  ·  Real video feed demo  ·  API docs

scroll_spy is the layer between raw Flutter widget visibility and a product decision. It reports every visible and focused item, then applies an explicit policy and stability rules to select one primaryId. A video engine can pause the previous ID and play the next without two half-visible cards fighting over audio.

What it answers

Every scrolling feed eventually needs to know:

• Which items are visible right now? (detach video controllers off-screen)
• Which items are inside my "attention area"? (a line or zone in the viewport)
• Which single item should be the one? (autoplay this card, highlight this TOC section, log this impression) - and how do I keep that choice from flickering while the user scrolls?

scroll_spy computes all of this for you, every scroll, with a configurable pipeline and zero manual geometry math:

scroll event
    |
    v
 Measure      each registered item's rect in viewport coordinates
    |
    v
 Region       does the item intersect the focus line/zone?  -> isFocused + metrics
    |
    v
 Policy       rank focused items, pick one winner            -> primary candidate
    |
    v
 Stability    hysteresis + min-duration to prevent flicker   -> primaryId
    |
    v
 Controller   ValueListenables: primaryId / focusedIds / snapshot / per-item

Why this package

• A stable primary, not just visibility. Visibility detection tells you an item is 60% on screen. scroll_spy additionally picks one winner using a policy (closest to anchor, largest visible fraction, ...) and smooths it with hysteresis and minimum-hold-time so autoplay does not stutter between two half-visible cards.
• Rich per-item metrics. visibleFraction, distanceToAnchorPx, focusProgress (0..1 center-closeness, great for scale/parallax effects), and focusOverlapFraction.
• Built for scroll performance. During steady scrolling the engine derives each item's position with O(1) arithmetic from a cached scroll model - no render-tree walks, no matrix math, no allocations on the hot path. Snapshots are materialized lazily, only when something listens. Items under transforms or exotic custom slivers are detected automatically and measured with a general path, so correctness never depends on your layout being "standard".
• Granular rebuild control. Per-item notifiers, boolean-only "lite" items, diff-only global signals, and listener widgets for side effects that should not rebuild anything.
• A real debug overlay. Paint the focus region, item bounds, and primary/focused outlines directly over your list while you tune it.

How it differs from visibility detection

Choose by the decision your screen needs: