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
• WidgetExtension

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

makeRefreshable → Widget

Available on Widget?, provided by the WidgetExtension extension

Make your any widget refreshable with RefreshIndicator on top

no setter

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

center({double? heightFactor, double? widthFactor}) → Widget

Available on Widget?, provided by the WidgetExtension extension

set parent widget in center

colorFilter([ColorFilter? colorFilter]) → Widget

Available on Widget, provided by the GenericExtensions extension

set parent widget in center

cornerRadiusWithClipRRect(double radius) → ClipRRect

Available on Widget?, provided by the WidgetExtension extension

add corner radius

cornerRadiusWithClipRRectOnly({int bottomLeft = 0, int bottomRight = 0, int topLeft = 0, int topRight = 0}) → ClipRRect

Available on Widget?, provided by the WidgetExtension extension

add custom corner radius each side

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

expand({int flex = 1}) → Widget

Available on Widget?, provided by the WidgetExtension extension

add Expanded to parent widget

fit({BoxFit? fit, AlignmentGeometry? alignment}) → Widget

Available on Widget?, provided by the WidgetExtension extension

add FittedBox to parent widget

flexible({int flex = 1, FlexFit? fit}) → Widget

Available on Widget?, provided by the WidgetExtension extension

add Flexible to parent widget

launch<T>(BuildContext context, {bool isNewTask = false, PageRouteAnimation? pageRouteAnimation, Duration? duration, String? routeName, Object? routeArguments}) → Future<T?>

Available on Widget?, provided by the WidgetExtension extension

Launch a new screen

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

onTap(Function? function, {BorderRadius? borderRadius, Color? splashColor, Color? hoverColor, Color? highlightColor, Color? focusColor, WidgetStateProperty<Color?>? overlayColor}) → Widget

Available on Widget?, provided by the WidgetExtension extension

add tap to parent widget

opacity({required double opacity, int durationInSecond = 1, Duration? duration}) → Widget

Available on Widget?, provided by the WidgetExtension extension

add opacity to parent widget

paddingAll(double padding) → Padding

Available on Widget?, provided by the WidgetExtension extension

return padding all

paddingBottom(double bottom) → Padding

Available on Widget?, provided by the WidgetExtension extension

return padding bottom

paddingDirectional({double start = 0.0, double top = 0.0, double end = 0.0, double bottom = 0.0}) → Widget

Available on Widget?, provided by the WidgetExtension extension

paddingLeft(double left) → Padding

Available on Widget?, provided by the WidgetExtension extension

return padding left

paddingOnly({double top = 0.0, double left = 0.0, double bottom = 0.0, double right = 0.0}) → Padding

Available on Widget?, provided by the WidgetExtension extension

return custom padding from each side

paddingRight(double right) → Padding

Available on Widget?, provided by the WidgetExtension extension

return padding right

paddingSymmetric({double vertical = 0.0, double horizontal = 0.0}) → Padding

Available on Widget?, provided by the WidgetExtension extension

return padding symmetric

paddingTop(double top) → Padding

Available on Widget?, provided by the WidgetExtension extension

return padding top

rotate({required double angle, bool transformHitTests = true, Offset? origin}) → Widget

Available on Widget?, provided by the WidgetExtension extension

add rotation to parent widget

scale({required double scale, Offset? origin, AlignmentGeometry? alignment, bool transformHitTests = true}) → Widget

Available on Widget?, provided by the WidgetExtension extension

add scaling to parent widget

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

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

inherited

tooltip({required String msg}) → Widget

Available on Widget?, provided by the WidgetExtension extension

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

translate({required Offset offset, bool transformHitTests = true, Key? key}) → Widget

Available on Widget?, provided by the WidgetExtension extension

add translate to parent widget

validate({Widget value = const SizedBox()}) → Widget

Available on Widget?, provided by the WidgetExtension extension

Validate given widget is not null and returns given value if null.

visible(bool visible, {Widget? defaultWidget}) → Widget

Available on Widget?, provided by the WidgetExtension extension

set visibility

withHeight(double height) → SizedBox

Available on Widget?, provided by the WidgetExtension extension

With custom height

withRoundedCorners({Color backgroundColor = whiteColor, BorderRadius borderRadius = const BorderRadius.all(Radius.circular(8.0)), LinearGradient? gradient, BoxBorder? border, List<BoxShadow>? boxShadow, DecorationImage? decorationImage, BoxShape boxShape = BoxShape.rectangle}) → Container

Available on Widget?, provided by the WidgetExtension extension

withScroll({ScrollPhysics? physics, EdgeInsetsGeometry? padding, Axis scrollDirection = Axis.vertical, ScrollController? controller, DragStartBehavior dragStartBehavior = DragStartBehavior.start, bool? primary, required bool reverse}) → Widget

Available on Widget?, provided by the WidgetExtension extension

withShaderMask(List<Color> colors, {BlendMode blendMode = BlendMode.srcATop}) → Widget

Available on Widget?, provided by the WidgetExtension extension

Wrap with ShaderMask widget

withShaderMaskGradient(Gradient gradient, {BlendMode blendMode = BlendMode.srcATop}) → Widget

Available on Widget?, provided by the WidgetExtension extension

Wrap with ShaderMask widget Gradient

withShadow({Color bgColor = whiteColor, Color shadowColor = Colors.black12, dynamic blurRadius = 10.0, dynamic spreadRadius = 0.0, Offset offset = const Offset(0.0, 0.0), LinearGradient? gradient, BoxBorder? border, DecorationImage? decorationImage, BoxShape boxShape = BoxShape.rectangle}) → Container

Available on Widget?, provided by the WidgetExtension extension

withSize({double width = 0.0, double height = 0.0}) → SizedBox

Available on Widget?, provided by the WidgetExtension extension

With custom height and width

withTooltip({required String msg}) → Widget

Available on Widget?, provided by the WidgetExtension extension

Validate given widget is not null and returns given value if null.

withVisibility(bool visible, {Widget? replacement, bool maintainAnimation = false, bool maintainState = false, bool maintainSize = false, bool maintainSemantics = false, bool maintainInteractivity = false}) → Visibility

Available on Widget?, provided by the WidgetExtension extension

set widget visibility

withWidth(double width) → SizedBox

Available on Widget?, provided by the WidgetExtension extension

With custom width

Operators

operator ==(Object other) → bool

The equality operator.

inherited