IndexScrollListViewBuilder class

A highly customizable ListView.builder with built-in index-based scrolling capabilities.

This widget extends the functionality of Flutter's standard ListView.builder by adding the ability to programmatically scroll to any item by its index, even before that item has been built or is off-screen.

Key features:

• Index-based scrolling: Jump to any item in the list by index
• Automatic scroll on initialization: Optionally scroll to a specific item when the list is first built
• Smooth animations: Configurable animation duration and curves
• Smart positioning: Control where items appear in the viewport (alignment)
• Offset support: Scroll to an item while keeping previous items visible
• Optional scrollbar: Built-in scrollbar support with full customization
• Unbounded constraint handling: Automatically manages shrinkWrap based on layout constraints

Example - Basic usage:

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

Example - Scroll to specific index on initialization:

IndexScrollListViewBuilder(
  itemCount: 100,
  indexToScrollTo: 50,  // Automatically scrolls to item 50
  itemBuilder: (context, index) => ListTile(
    title: Text('Item $index'),
  ),
)

Example - With custom controller for programmatic control:

final controller = IndexedScrollController();

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

// Later, scroll programmatically
controller.scrollToIndex(75);

See also:

• ListView.builder, the underlying widget being enhanced
• IndexedScrollController, which manages the scrolling logic
• IndexedScrollTag, which tags each item for scrolling

Inheritance

• Object
• DiagnosticableTree
• Widget
• StatefulWidget
• IndexScrollListViewBuilder

Available extensions

• AnimateWidgetExtensions
• GenericExtensions

Constructors

IndexScrollListViewBuilder({Key? key, required Widget itemBuilder(BuildContext, int), required int itemCount, Axis? scrollDirection, ScrollPhysics? physics, bool? shrinkWrap, int? indexToScrollTo, int numberOfOffsetedItemsPriorToSelectedItem = 1, double? startPadding, IndexedScrollController? controller, required void onScrolledTo(int index), Duration scrollAnimationDuration = const Duration(milliseconds: 400), double? scrollAlignment, EdgeInsetsGeometry? padding, bool showScrollbar = false, bool? scrollbarThumbVisibility, bool? scrollbarTrackVisibility, double? scrollbarThickness, Radius? scrollbarRadius, ScrollbarOrientation? scrollbarOrientation, bool? scrollbarInteractive, bool suppressPlatformScrollbars = false, int? autoScrollMaxFrameDelay, int? autoScrollEndOfFrameDelay})

Creates an IndexScrollListViewBuilder.

const

Properties

autoScrollEndOfFrameDelay → int?

Number of frames to wait at the end of auto-scroll.

final

autoScrollMaxFrameDelay → int?

Maximum number of frames to wait before initiating auto-scroll.

final

controller → IndexedScrollController?

Optional IndexedScrollController to use for this list.

final

hashCode → int

The hash code for this object.

no setter, inherited

indexToScrollTo → int?

Optional index to automatically scroll to when the widget rebuilds.

final

itemBuilder → Widget Function(BuildContext, int)

Builder function that creates widgets for each item in the list.

final

itemCount → int

The total number of items in the list.

final

key → Key?

Controls how one widget replaces another widget in the tree.

final, inherited

numberOfOffsetedItemsPriorToSelectedItem → int

Number of items to show before the target item when scrolling.

final

onScrolledTo → void Function(int index)

Unified callback invoked whenever the list scrolls to an index as a result of either declarative indexToScrollTo or a programmatic controller.scrollToIndex(...).

final

padding → EdgeInsetsGeometry?

Padding around the list content.

final

physics → ScrollPhysics?

The scroll physics for the list.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

scrollAlignment → double?

The alignment of the target item in the viewport (0.0 to 1.0).

final

scrollAnimationDuration → Duration

Duration of the scroll animation.

final

scrollbarInteractive → bool?

Whether the scrollbar can be dragged for seeking.

final

scrollbarOrientation → ScrollbarOrientation?

Which side of the list to show the scrollbar.

final

scrollbarRadius → Radius?

The radius of the scrollbar corners.

final

scrollbarThickness → double?

The thickness of the scrollbar.

final

scrollbarThumbVisibility → bool?

Whether the scrollbar thumb should always be visible.

final

scrollbarTrackVisibility → bool?

Whether the scrollbar track should always be visible.

final

scrollDirection → Axis?

The axis along which the list scrolls.

final

showScrollbar → bool

Whether to show a scrollbar.

final

shrinkWrap → bool?

Whether the list should shrink-wrap its content.

final

startPadding → double?

Starting padding for the list.

final

suppressPlatformScrollbars → bool

Whether to suppress platform-specific scrollbars.

final

Methods

addMaterialWidget() → Material

Available on Widget, provided by the GenericExtensions extension

addTooltipWidget(String toolTip) → Tooltip

Available on Widget, provided by the GenericExtensions extension

animate({Key? key, List<Effect>? effects, AnimateCallback? onInit, AnimateCallback? onPlay, AnimateCallback? onComplete, bool? autoPlay, Duration? delay, AnimationController? controller, Adapter? adapter, double? target, double? value}) → Animate

Available on Widget, provided by the AnimateWidgetExtensions extension

Wraps the target Widget in an Animate instance, and returns the instance for chaining calls. Ex. myWidget.animate() is equivalent to Animate(child: myWidget).

borderRadius([BorderRadiusGeometry? borderRadius]) → Widget

Available on Widget, provided by the GenericExtensions extension

boxDecoration([BoxDecoration? boxDecoration]) → Widget

Available on Widget, provided by the GenericExtensions extension

colorFilter([ColorFilter? colorFilter]) → Widget

Available on Widget, provided by the GenericExtensions extension

set parent widget in center

createElement() → StatefulElement

Creates a StatefulElement to manage this widget's location in the tree.

inherited

createState() → State<IndexScrollListViewBuilder>

Creates the mutable state for this widget at a given location in the tree.

override

debugDescribeChildren() → List<DiagnosticsNode>

Returns a list of DiagnosticsNode objects describing this node's children.

inherited

debugFillProperties(DiagnosticPropertiesBuilder properties) → void

Add additional properties associated with the node.

inherited

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode

Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.

inherited

toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String

A string representation of this object.

inherited

toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String

Returns a string representation of this node and its descendants.

inherited

toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String

Returns a one-line detailed description of the object.

inherited

toStringShort() → String

A short, textual description of this widget.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited