indexscroll_listview_builder #

Enhanced ListView.builder for Flutter with powerful bidirectional index-based programmatic scrolling, precise viewport control, item alignment, offset handling, and optional customizable scrollbar.

📱 Demo #

Interactive demonstration showing bidirectional scrolling, auto-scroll with alignment control, and external controller buttons

✨ Features #

• 🎯 Bidirectional scrolling: Scroll to any item by index - works perfectly both up and down the list
• 🚀 Viewport-based precision: Direct viewport offset calculations for accurate positioning
• ⚡ Off-screen item support: Scroll to items not yet rendered with smart position estimation
• 🎮 Automatic initial scroll: Navigate to target index on widget build via indexToScrollTo
• 📍 Offset support: Keep items before the target visible (numberOfOffsetedItemsPriorToSelectedItem)
• 🎨 Customizable alignment: Position target item anywhere in viewport with scrollAlignment (0.0–1.0)
• 🕹️ External controller: Advanced programmatic control with IndexedScrollController
• 📜 Optional scrollbar: Full customization (thumb, track, thickness, radius, orientation)
• 🔄 Operation cancellation: Superseded scroll operations are cancelled to prevent interrupted animations
• 📱 Smart shrinkWrap: Automatic handling for unbounded constraints
• ✨ Smooth animations: Configurable duration and curve
• 🎬 Frame-delayed execution: Reduces layout jank during scroll operations

🛠 Installation #

Add to your pubspec.yaml:

dependencies:
  indexscroll_listview_builder: ^2.0.2

Then import:

import 'package:indexscroll_listview_builder/indexscroll_listview_builder.dart';

🚀 Quick Start #

IndexScrollListViewBuilder(
  itemCount: 100,
  itemBuilder: (context, index) => ListTile(title: Text('Item #$index')),
)

🎯 Auto Scroll on Build #

Automatically scroll to a target index when the widget builds:

IndexScrollListViewBuilder(
  itemCount: 50,
  indexToScrollTo: 25, // scroll after first frame
  numberOfOffsetedItemsPriorToSelectedItem: 2, // keep previous 2 items visible
  itemBuilder: (context, index) => ListTile(
    title: Text('Item #$index'),
  ),
)

🧭 External Controller #

Use an IndexedScrollController for programmatic control:

final controller = IndexedScrollController();
final itemCount = 100;

IndexScrollListViewBuilder(
  controller: controller,
  itemCount: itemCount,
  itemBuilder: (context, index) => ListTile(title: Text('Item #$index')),
);

// Later (e.g. button press)
await controller.scrollToIndex(75, itemCount: itemCount, alignmentOverride: 0.3);

// Scroll to first item
await controller.scrollToIndex(0, itemCount: itemCount);

// Scroll to last item  
await controller.scrollToIndex(itemCount - 1, itemCount: itemCount);

🪟 Scrollbar Example #

IndexScrollListViewBuilder(
  itemCount: 80,
  showScrollbar: true,
  scrollbarThumbVisibility: true,
  scrollbarThickness: 8,
  scrollbarRadius: const Radius.circular(8),
  itemBuilder: (context, index) => ListTile(title: Text('Item #$index')),
)

📐 Alignment & Offset #

scrollAlignment #

Controls where the target item appears in the viewport:

• 0.0 - Item aligns at the start (top for vertical, left for horizontal)
• 0.5 - Item appears centered in the viewport
• 1.0 - Item aligns at the end (bottom for vertical, right for horizontal)
• Default: 0.2 (20% from start)

numberOfOffsetedItemsPriorToSelectedItem #

Shifts the scroll position backward to keep previous items visible:

• 1 - Shows the target item (default)
• 2 - Shows 1 item before the target
• 3 - Shows 2 items before the target
• etc.

Example:

IndexScrollListViewBuilder(
  indexToScrollTo: 50,
  numberOfOffsetedItemsPriorToSelectedItem: 3, // Shows items 48, 49, 50
  scrollAlignment: 0.0, // Items 48-50 appear at top
  itemCount: 100,
  itemBuilder: (context, index) => ListTile(title: Text('Item $index')),
)

🧪 Example Application #

See the complete interactive example in example/lib/main.dart demonstrating:

• Basic List: Simple list with 100 items
• Auto-scroll Demo: Dynamic target selection with slider, offset control, and alignment settings
• External Controller: Comprehensive button controls:
  • Scroll to First/Last item
  • Jump +10/-10 items
  • Direct index input
  • Perfect handling of list boundaries

Run the example:

cd example
flutter run

🔍 API Overview #

IndexScrollListViewBuilder #

Primary widget that extends ListView.builder with index-based scrolling capabilities.

Key Methods:

• Automatically wraps items with IndexedScrollTag for registration
• Handles viewport constraints and shrinkWrap logic
• Manages scroll controller lifecycle

IndexedScrollController #

Core controller that powers the scrolling mechanism.

Key Methods:

• scrollToIndex(int index, {required int itemCount, double? alignmentOverride}) - Scroll to specific index
• register(int index, GlobalKey key) - Register an item (called internally)
• unregister(int index) - Unregister an item (called internally)

Features:

• Maintains registry of GlobalKeys for each list item
• Smart index resolution with fallback logic
• Viewport-based offset calculation
• Operation versioning for cancellation
• Special handling for list extremes (first/last items)

IndexedScrollTag #

Internal widget that tags each list item for the controller.

Lifecycle:

• Registers item on initState
• Updates registration on index/controller changes
• Unregisters on dispose

⚙ Parameters #

Core Parameters #

Scrolling Behavior #

Scrollbar Customization #

Advanced Options #

� Technical Details #

How It Works #

1. Registration System: Each list item is wrapped with IndexedScrollTag that registers a GlobalKey with the controller
2. Index Resolution: When scrolling to an index, the controller finds the nearest registered key using smart fallback logic
3. Viewport Calculation: Uses RenderAbstractViewport.getOffsetToReveal to calculate precise scroll offsets
4. Off-screen Estimation: For items not yet rendered, estimates position based on visible items and animates there
5. Operation Versioning: Each scroll operation gets a version number; superseded operations are cancelled

Edge Cases Handled #

• First item (index 0): Always scrolls to offset 0.0 for perfect alignment
• Last item: Uses maxScrollExtent to ensure full visibility
• Rapid scrolling: Operation cancellation prevents interrupted animations
• Off-screen items: Position estimation enables scrolling before item is built
• Dynamic lists: Handles controller and index changes gracefully

Performance Considerations #

• Fast-path optimization: Checks exact index before searching all registered keys
• Const constructors: All widgets use const constructors where possible
• Key caching: GlobalKeys are created once and reused across rebuilds
• Frame-delayed execution: Reduces layout jank during scroll operations

�📄 CHANGELOG #

See CHANGELOG.md for detailed version history.

📜 License #

Licensed under the MIT License. See LICENSE.

🔗 Repository & Issues #

Repository: https://github.com/SoundSliced/indexscroll_listview_builder
Issues: https://github.com/SoundSliced/indexscroll_listview_builder/issues

🙌 Contributing #

Contributions welcome! Feel free to open issues or PRs for improvements, examples, or documentation refinements.

If this package helps you, Like it on Pub.dev, and add a ⭐ on GitHub. This is appreciated!

❓ FAQ #

Q: Can I scroll to items that haven't been built yet? #

A: Yes! Version 2.0.0 estimates the position of off-screen items and scrolls there smoothly.

Q: Why does scrollToIndex require itemCount in v2.0.0? #

A: The itemCount parameter enables accurate position estimation for off-screen items, especially when scrolling to the last item or items near the end.

Q: How do I scroll to the exact last item? #

A: Use controller.scrollToIndex(itemCount - 1, itemCount: itemCount). The controller automatically uses maxScrollExtent for the last index.

Q: What happens if I scroll rapidly or drag a slider? #

A: Version 2.0.0 includes operation versioning that cancels superseded scroll operations, ensuring smooth animations without interruption.

Q: Can I use this with horizontal lists? #

A: Yes! Set scrollDirection: Axis.horizontal and the package handles everything correctly.

Q: Does this work with dynamic lists that change size? #

A: Yes, the registration system automatically handles items being added or removed. The controller maintains a registry that updates as widgets are built/disposed.