ListView

The ListView widget is a scrollable list that lays items out along a single axis — vertical by default.
It draws one item for every entry in your data, so use it for screens where items run continuously, such as lists, feeds, and search results.

Definition and role

The ListView widget places child items in order along the axis you choose, and lets you keep scrolling once the content runs past the visible area. The number of repeated items grows and shrinks with the data you bind, and you can set the spacing between items, the padding inside the list, the scroll direction, the scroll physics, and more. It also covers infinite scroll — catch the event that fires when scrolling reaches the end, then load the next batch of data.

• Category: Layouts
• Default scroll direction: vertical
• Default item count: 0

Features

Feature	Description
Repeated item rendering	Draws one child item for every entry in the bound data (itemCount).
Scroll direction	Lays items out and scrolls them vertically (vertical) or horizontally (horizontal).
Item spacing	Adds even spacing between items with the spacing value.
End-of-scroll detection	When scrolling reaches the end of the list, onScrollEnd fires — use it to load more items (infinite scroll).
Overflow clipping	Set overflowMode to clip to crop items to the area you defined and report how many were cut.
Entrance animation	Use the animation setting to give items a staggered entrance effect.

How to use

1. Open the Layouts category in the left widget palette.
2. Drag and drop the ListView item onto the canvas.
3. Place the child widgets you want to repeat inside the list.
4. In the Properties panel on the right, bind itemCount to your data or set a fixed count.
5. Adjust the scroll direction (scrollDirection), item spacing (spacing), and padding (padding) as needed.

Properties

Property	Description	Default	Values / type
scrollDirection	Direction items are laid out and scrolled in	vertical	horizontal, vertical
reverse	Displays items in reverse order	Off (false)	true / false
shrinkWrap	Shrinks the list to fit its content	On (true)	true / false
spacing	Spacing between items	Not set	Number
padding	Padding inside the list	Not set	Padding
controller	Controller that drives scrolling	Not set	Scroll controller
primary	Whether to use this as the screen's primary scroll view	Not set	true / false
physics	Scroll physics	Not set	bouncing, clamping, alwaysScrollable, rangeMaintaining, neverScrollable, page
itemExtent	Fixed size of each item along the main axis	Not set	Number
addAutomaticKeepAlives	Keeps the state of off-screen items alive automatically	On (true)	true / false
addRepaintBoundaries	Adds a repaint boundary around each item	On (true)	true / false
addSemanticIndexes	Assigns accessibility indexes to items automatically	On (true)	true / false
cacheExtent	Size of the area built ahead of time off-screen	Not set	Number
semanticChildCount	Number of items reported to accessibility	Not set	Integer
itemCount	Number of items to draw repeatedly (supports data binding)	0	Integer
dragStartBehavior	When a drag-to-scroll gesture starts	start	start, down
keyboardDismissBehavior	How the keyboard is dismissed while scrolling	manual	manual, onDrag
restorationId	Identifier used to restore the scroll position	Not set	String
clipBehavior	How content outside the area is clipped	hardEdge	none, hardEdge, antiAlias, antiAliasWithSaveLayer
animation	Staggered entrance animation settings for items	Not set	Animation settings
overflowMode	How items that overflow the area are handled	none	none, clip
reservedTrailingExtent	Extra width to leave empty out of the available width in clip mode	Not set	Number

Notes and tips

tip

onScrollEnd fires once when scrolling reaches the end of the list, and arms itself again as soon as you scroll away from the end. Use it for infinite scroll that loads the next page.

warning

scrollToIndex and getFirstVisibleIndex only work when itemExtent — the fixed item size — is set. Without a value, scrolling to an index does nothing and the first visible index returns 0.

Learn more

tip

For the full set of Widget Control members (Property, Method, and Event) that drive this widget from a script, see ListView Widget Control.