IndexedScrollController class

A specialized scroll controller that enables programmatic scrolling to specific indexed items within a scrollable list.

This controller extends the functionality of a standard ScrollController by maintaining a registry of GlobalKeys associated with list item indices. This allows for precise scrolling to any item in the list by its index, even if the item hasn't been built yet or is off-screen.

The controller uses viewport offset calculations to smoothly animate the scroll position and bring the target item into view. It includes intelligent handling for edge cases like scrolling to the last item and off-screen items.

Example usage:

final controller = IndexedScrollController(
  duration: Duration(milliseconds: 300),
  alignment: 0.2, // Position item at 20% from top
);

// Later, scroll to index 10
controller.scrollToIndex(10);

See also:

• IndexedScrollTag, which registers items with this controller
• IndexScrollListViewBuilder, which integrates this controller with ListView

Constructors

IndexedScrollController({ScrollController? scrollController, Duration duration = const Duration(milliseconds: 500), Curve curve = Curves.easeOut, double alignment = 0.2, ScrollPositionAlignmentPolicy alignmentPolicy = ScrollPositionAlignmentPolicy.keepVisibleAtStart, int endOfFramePasses = 6, int maxFramePasses = 12})

Creates an IndexedScrollController.

Properties

alignment → double

Default alignment for positioning items in the viewport (0.0 to 1.0).

final

alignmentPolicy → ScrollPositionAlignmentPolicy

Default policy for aligning items in the viewport.

final

controller → ScrollController

Provides access to the underlying ScrollController.

no setter

curve → Curve

Default animation curve for scroll operations.

final

duration → Duration

Default animation duration for scroll operations.

final

endOfFramePasses → int

Number of frame passes to wait at the end of a scroll operation.

final

hashCode → int

The hash code for this object.

no setter, inherited

maxFramePasses → int

Maximum number of frames to wait before initiating a scroll operation.

final

programmaticScrollIndex → ValueNotifier<int?>

Notifies listeners when a programmatic scroll is requested via scrollToIndex. Emits the desired target index (before resolution) so consumers can react.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

dispose() → void

Disposes of the underlying scroll controller if it was created by this instance.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

registerKey({required int index, required GlobalKey<State<StatefulWidget>> key}) → void

Registers a GlobalKey for a specific item index.

scrollToIndex(int index, {Duration? duration, Curve? curveOverride, double? alignmentOverride, ScrollPositionAlignmentPolicy? alignmentPolicyOverride, int? maxFrameDelay, int? endOfFrameDelay, required int? itemCount}) → Future<void>

Scrolls to the item at the given index with animation.

toString() → String

A string representation of this object.

inherited

unregisterKey(GlobalKey<State<StatefulWidget>> key) → void

Unregisters a GlobalKey from the controller.

updateKeyIndex({required int? oldIndex, required int newIndex, required GlobalKey<State<StatefulWidget>> key}) → void

Updates a key's registration from an old index to a new index.

Operators

operator ==(Object other) → bool

The equality operator.

inherited