Skip to main content

ListView

Scrollable list of widgets. For small lists, use ListView with all items in memory. For large lists, use ListViewBuilder with ItemExtent for virtualization.

Basic ListView​

widgets.ListView{
Children: []core.Widget{
item1,
item2,
item3,
},
Padding: layout.EdgeInsetsAll(16),
}

ListViewBuilder (Virtualized)​

For large lists, ListViewBuilder with ItemExtent only builds visible items:

widgets.ListViewBuilder{
ItemCount: 1000,
ItemExtent: 60, // Required for virtualization
CacheExtent: 100, // Extra pixels to render beyond viewport
ItemBuilder: func(ctx core.BuildContext, index int) core.Widget {
item := items[index]
return widgets.Container{
Padding: layout.EdgeInsetsAll(16),
Child: widgets.Text{Content: item.Title},
}
},
}

Properties​

ListView​

PropertyTypeDescription
Children[]core.WidgetList items
ScrollDirectionAxisAxisVertical (default) or AxisHorizontal
Controller*ScrollControllerManages scroll position and provides scroll notifications
PhysicsScrollPhysicsScroll behavior; see ScrollView
Paddinglayout.EdgeInsetsPadding around the list
MainAxisAlignmentMainAxisAlignmentHow children are positioned along the scroll axis
MainAxisSizeMainAxisSizeHow much space the list takes along the scroll axis

ListViewBuilder​

PropertyTypeDescription
ItemCountintTotal number of items
ItemBuilderfunc(BuildContext, int) WidgetBuilds a widget for the given index
ItemExtentfloat64Fixed item height (enables virtualization)
CacheExtentfloat64Extra pixels to render beyond the viewport
ScrollDirectionAxisAxisVertical (default) or AxisHorizontal
Controller*ScrollControllerManages scroll position and provides scroll notifications
PhysicsScrollPhysicsScroll behavior; see ScrollView
Paddinglayout.EdgeInsetsPadding around the list
MainAxisAlignmentMainAxisAlignmentHow children are positioned along the scroll axis
MainAxisSizeMainAxisSizeHow much space the list takes along the scroll axis

ItemExtent is Required for Virtualization​

ItemExtent (fixed item height) enables virtualization. Without it, all items are built upfront:

// Virtualized: only visible items are built
widgets.ListViewBuilder{
ItemCount: 1000,
ItemExtent: 60, // All items are 60 pixels tall
ItemBuilder: buildItem,
}

// NOT virtualized: all items built upfront
widgets.ListViewBuilder{
ItemCount: 1000,
// ItemExtent omitted - no virtualization
ItemBuilder: buildItem,
}

When to Use ListViewBuilder​

ScenarioRecommendation
< 50 itemsListView is fine
50+ fixed-height itemsListViewBuilder with ItemExtent
Variable-height itemsListView or accept no virtualization

Scroll Direction​

widgets.ListView{
ScrollDirection: widgets.AxisHorizontal, // Defaults to vertical
Children: items,
}