A scrollable list of widgets arranged linearly.

ListView is the most commonly used scrolling widget. It displays its children one after another in the scroll direction. In the cross axis, the children are required to fill the ListView.

If non-null, the itemExtent forces the children to have the given extent in the scroll direction. Specifying an itemExtent is more efficient than letting the children determine their own extent because the scrolling machinery can make use of the foreknowledge of the children's extent to save work, for example when the scroll position changes drastically.

There are three options for constructing a ListView:

  1. The default constuctor takes an explict List of children. This constructor is appropriate for list views with a small number of children because constructing the List requires doing work for every child that could possibly be displayed in the list view instead of just those children that are actually visible.

  2. The ListView.builder takes an IndexedWidgetBuilder, which builds the children on demand. This constructor is appropriate for list views with a large (or infinite) number of children because the builder is called only for those children that are actually visible.

  3. The ListView.custom takes a SliverChildDelegate, which provides the ability to customize additional aspects of the child model. For example, a SliverChildDelegate can control the algorithm used to estimate the size of children that are not actually visible.

To control the initial scroll offset of the scroll view, provide a controller with its ScrollController.initialScrollOffset property set.

Sample code

An infinite list of children:

new ListView.builder(
  padding: new EdgeInsets.all(8.0),
  itemExtent: 20.0,
  itemBuilder: (BuildContext context, int index) {
    return new Text('entry $index');
  },
)

Transitioning to CustomScrollView

A ListView is basically a CustomScrollView with a single SliverList in its CustomScrollView.slivers property.

If ListView is no longer sufficient, for example because the scroll view is to have both a list and a grid, or because the list is to be combined with a SliverAppBar, etc, it is straight-forward to port code from using ListView to using CustomScrollView directly.

The key, scrollDirection, reverse, controller, primary, physics, and shrinkWrap properties on ListView map directly to the identically named properties on CustomScrollView.

The CustomScrollView.slivers property should be a list containing either a SliverList or a SliverFixedExtentList; the former if itemExtent on the ListView was null, and the latter if itemExtent was not null.

The childrenDelegate property on ListView corresponds to the SliverList.delegate (or SliverFixedExtentList.delegate) property. The new ListView constructor's children argument corresponds to the childrenDelegate being a SliverChildListDelegate with that same argument. The new ListView.builder constructor's itemBuilder and childCount arguments correspond to the childrenDelegate being a SliverChildBuilderDelegate with the matching arguments.

The padding property corresponds to having a SliverPadding in the CustomScrollView.slivers property instead of the list itself, and having the SliverList instead be a child of the SliverPadding.

Once code has been ported to use CustomScrollView, other slivers, such as SliverGrid or SliverAppBar, can be put in the CustomScrollView.slivers list.

Sample code

Here are two brief snippets showing a ListView and its equivalent using CustomScrollView:

new ListView(
  shrinkWrap: true,
  padding: const EdgeInsets.all(20.0),
  children: <Widget>[
    const Text('I\'m dedicating every day to you'),
    const Text('Domestic life was never quite my style'),
    const Text('When you smile, you knock me out, I fall apart'),
    const Text('And I thought I was so smart'),
  ],
)
new CustomScrollView(
  shrinkWrap: true,
  slivers: <Widget>[
    new SliverPadding(
      padding: const EdgeInsets.all(20.0),
      sliver: new SliverList(
        delegate: new SliverChildListDelegate(
          <Widget>[
            const Text('I\'m dedicating every day to you'),
            const Text('Domestic life was never quite my style'),
            const Text('When you smile, you knock me out, I fall apart'),
            const Text('And I thought I was so smart'),
          ],
        ),
      ),
    ),
  ],
)

See also:

Inheritance

Constructors

ListView({Key key, Axis scrollDirection: Axis.vertical, bool reverse: false, ScrollController controller, bool primary, ScrollPhysics physics, bool shrinkWrap: false, EdgeInsets padding, double itemExtent, bool addAutomaticKeepAlives: true, bool addRepaintBoundaries: true, List<Widget> children: const [] })
Creates a scrollable, linear array of widgets from an explicit List. [...]
ListView.builder({Key key, Axis scrollDirection: Axis.vertical, bool reverse: false, ScrollController controller, bool primary, ScrollPhysics physics, bool shrinkWrap: false, EdgeInsets padding, double itemExtent, @required IndexedWidgetBuilder itemBuilder, int itemCount, bool addAutomaticKeepAlives: true, bool addRepaintBoundaries: true })
Creates a scrollable, linear array of widgets that are created on demand. [...]
ListView.custom({Key key, Axis scrollDirection: Axis.vertical, bool reverse: false, ScrollController controller, bool primary, ScrollPhysics physics, bool shrinkWrap: false, EdgeInsets padding, double itemExtent, @required SliverChildDelegate childrenDelegate })
Creates a scrollable, linear array of widgets with a custom child model. [...]

Properties

childrenDelegate SliverChildDelegate
A delegate that provides the children for the ListView. [...]
final
itemExtent double
If non-null, forces the children to have the given extent in the scroll direction. [...]
final
controller ScrollController
An object that can be used to control the position to which this scroll view is scrolled. [...]
final, inherited
hashCode int
The hash code for this object. [...]
read-only, inherited
key Key
Controls how one widget replaces another widget in the tree. [...]
final, inherited
padding EdgeInsets
The amount of space by which to inset the children.
final, inherited
physics ScrollPhysics
How the scroll view should respond to user input. [...]
final, inherited
primary bool
Whether this is the primary scroll view associated with the parent PrimaryScrollController. [...]
final, inherited
reverse bool
Whether the scroll view scrolls in the reading direction. [...]
final, inherited
runtimeType Type
A representation of the runtime type of the object.
read-only, inherited
scrollDirection Axis
The axis along which the scroll view scrolls. [...]
final, inherited
shrinkWrap bool
Whether the extent of the scroll view in the scrollDirection should be determined by the contents being viewed. [...]
final, inherited

Methods

buildChildLayout(BuildContext context) Widget
Subclasses should override this method to build the layout model.
debugFillProperties(DiagnosticPropertiesBuilder description) → void
build(BuildContext context) Widget
Describes the part of the user interface represented by this widget. [...]
inherited
buildSlivers(BuildContext context) List<Widget>
Subclasses should override this method to build the slivers for the inside of the viewport.
inherited
createElement() StatelessElement
Creates a StatelessElement to manage this widget's location in the tree. [...]
inherited
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children. [...]
@protected, inherited
getDirection(BuildContext context) AxisDirection
Returns the AxisDirection in which the scroll view scrolls. [...]
@protected, inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent 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 toStringDeep. [...]
inherited
toString() String
Returns a string representation of this object.
inherited
toStringDeep([String prefixLineOne = '', String prefixOtherLines ]) String
Returns a string representation of this node and its descendants. [...]
inherited
toStringShallow([String joiner = ', ' ]) String
Returns a one-line detailed description of the object. [...]
inherited
toStringShort() String
A short, textual description of this widget.
inherited

Operators

operator ==(other) bool
The equality operator. [...]
inherited