indexscroll_listview_builder

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

✨ Features

Scroll directly to any item by its index (even if not yet built)
Automatic initial scroll via indexToScrollTo
Offset support: keep items before the target visible (numberOfOffsetedItemsPriorToSelectedItem)
Customizable alignment of target item in viewport (scrollAlignment)
External controller for advanced programmatic control (IndexedScrollController)
Optional scrollbar with full customization (thumb, track, thickness, radius, orientation)
Smart shrinkWrap handling for unbounded constraints
Smooth animations with configurable duration and curve
Special handling for last item visibility
Frame-delayed scroll execution to reduce layout jank

🛠 Installation

Add to your pubspec.yaml:

dependencies:
  indexscroll_listview_builder: ^1.0.0

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();

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

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

🪟 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 item appears in the viewport (0.0 = start, 0.5 = center, 1.0 = end).

numberOfOffsetedItemsPriorToSelectedItem shifts the effective scroll position backward so prior items remain visible.

🧪 Example Application

See the complete example in example/lib/main.dart with:

Basic list
Auto-scroll with dynamic target & offset
External controller demo with buttons
Scroll to last item handling

🔍 API Overview