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.3

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'),
  ),
)

Mixing Declarative and Imperative Scrolling #

When using both indexToScrollTo (declarative) and controller.scrollToIndex() (imperative), you may want to force re-scrolling to the same index:

final controller = IndexedScrollController();

IndexScrollListViewBuilder(
  controller: controller,
  itemCount: 100,
  indexToScrollTo: 25,
  forceAutoScroll: true, // Force scroll even if indexToScrollTo unchanged
  itemBuilder: (context, index) => ListTile(title: Text('Item #$index')),
)

// Later, scroll programmatically
await controller.scrollToIndex(75, itemCount: 100);

// Rebuild with same indexToScrollTo will still scroll back to 25
setState(() {}); // forceAutoScroll makes this re-scroll to index 25

🧭 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.

Q: How do I mix declarative (indexToScrollTo) and imperative (controller.scrollToIndex) scrolling? #

A: Use the forceAutoScroll: true parameter. This forces the list to re-scroll to indexToScrollTo on every rebuild, even if the value hasn't changed. This is useful when you programmatically scroll away using the controller but want rebuilds to restore the original scroll position.