ListView class

A vertically scrolling list that builds only the rows currently on screen.

Unlike wrapping a Column in a ScrollBox, this widget never inflates the off-screen rows: it asks itemBuilder only for the half-open window [scrollOffset, scrollOffset + visibleRows), so a list of a million items costs the same as a list of ten. That is the whole reason it exists — a ScrollBox would have to lay out every child to know its scroll extent.

The list has two modes, chosen by selectedIndex:

  • Selectable (selectedIndex is non-null): arrows, j/k, PageUp, PageDown, Home, and End move a highlight, which auto-scrolls to stay in view. Enter or a left click confirms it. onChanged reports the moved highlight and onSelect reports a confirmation.
  • Plain scroll (selectedIndex is null): the same keys move the window directly and no row is highlighted.

The mouse wheel scrolls the window in both modes without moving the highlight. A valid primary click in selectable mode is consumed after it confirms a row; plain-list and blank-row clicks remain available to ancestors.

The list occupies exactly height rows. A parent that offers fewer rows clips the overflow rather than shrinking the window, so give the list a height its parent can honor.

Give each row a stable key: ValueKey(id) to preserve its State while it remains in the visible window as the list scrolls or reorders. Rows outside the window are unmounted; state that must survive that belongs above the row.

Inheritance

Constructors

ListView({required int itemCount, required ListViewItemBuilder itemBuilder, Key? key, int itemExtent = 1, int height = 8, ViewportController? controller, int? selectedIndex, bool showScrollIndicator = false, Color? backgroundColor, Color? selectedBackgroundColor, FocusNode? focusNode, bool autofocus = false, ValueChanged<int>? onChanged, ValueChanged<int>? onSelect})
Configures a windowed list of itemCount rows, selectable when selectedIndex is non-null.
const

Properties

autofocus → bool
Whether this widget requests focus when first mounted.
final
backgroundColor → Color?
Fill painted behind the whole list. Falls back to ThemeData.surface under a Theme; with neither, the list paints no fill. Pass Color.transparent for an explicitly unfilled list inside a themed subtree.
final
controller → ViewportController?
Scroll position shared with the caller. One is created internally when null; a supplied controller is not disposed by this widget. Plain lists preserve its valid offset as content changes. Selectable lists also scroll to keep their highlight visible.
final
focusNode → FocusNode?
Focus node controlling this list's keyboard input. One is created if null.
final
hashCode → int
The hash code for this object.
no setterinherited
height → int
Rows of terminal height occupied by the whole list.
final
itemBuilder → ListViewItemBuilder
Builds the row at a given index; called only for visible rows.
final
itemCount → int
Total number of rows in the list.
final
itemExtent → int
Rows of terminal height occupied by each item.
final
key → Key?
Controls how this widget replaces another of the same type.
finalinherited
onChanged → ValueChanged<int>?
Called with the new index whenever the highlight moves. Never called in plain-scroll mode.
final
onSelect → ValueChanged<int>?
Called with the highlighted index when the user presses Enter or clicks a row. Never called in plain-scroll mode.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
selectedBackgroundColor → Color?
Fill painted behind the highlighted row while the list has focus. Falls back to ThemeData.selectedBackground. An unfocused list mutes its highlight to ThemeData.surfaceVariant, so with several lists on screen the accent fill marks the one that owns the keyboard.
final
selectedIndex → int?
Index highlighted when the list is first built, or null for a list with no selection. A later change to this value moves the highlight.
final
showScrollIndicator → bool
Whether to reserve the last column for scroll-direction arrows.
final

Methods

createState() → State<ListView>
Creates the mutable State for this widget.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited