GridView

The GridView widget is a scrollable list widget that arranges items in a grid.
Use it to repeat equally sized cells across multiple columns.

Definition and role

The GridView widget is an iterator widget that repeats one item template to draw a grid. Cells are laid out at a uniform size, and you set the number of columns either by how many cells fit in a row or by the maximum size of a single cell. Scroll direction, spacing, and cell ratio are all configurable.

• Category: Layouts
• Size on drop: 300 x 200 by default inside a parent layout such as Row, Column, or Stack. Dropped at the top level with no parent, it renders larger to fill the canvas.

Features

Feature	Description
Grid layout	Arranges items in a grid of several columns. Choose how the column count is determined with crossAxisType.
Column count and cell size	When crossAxisType is count, the cells per row (crossAxisCount) determine the column count; when it is extent, the maximum cell size (maxCrossAxisExtent) does.
Spacing and ratio	Adjust the cell spacing along the main and cross axes (mainAxisSpacing, crossAxisSpacing) and the width-to-height ratio of a cell (childAspectRatio).
Scrolling	Set the scroll direction (scrollDirection), reversed order (reverse), scroll physics (physics), and more.
Script control	Add and remove items, scroll to a specific item, and handle selection events from a script.

How to use

1. Open the Layouts category in the left widget palette.
2. Drag and drop the GridView item onto the canvas.
3. In the Properties panel on the right, choose crossAxisType. For count, set crossAxisCount (cells per row); for extent, set maxCrossAxisExtent (maximum cell size).
4. Tune the cell ratio and spacing with childAspectRatio, mainAxisSpacing, and crossAxisSpacing.
5. Place the item template you want to repeat inside the GridView.

Properties

Property	Description	Default	Values / type
crossAxisType	How the column count is determined — by cell count or by maximum cell size	count	count, extent
crossAxisCount	Number of cells per row (used when crossAxisType is count)	2	Number (integer, minimum 1)
maxCrossAxisExtent	Maximum cross-axis size of a single cell (used when crossAxisType is extent)	100	Number
scrollDirection	Scroll direction	vertical	horizontal, vertical
reverse	Whether to reverse the scroll direction	false	True / false
controller	Scroll controller	Not set	Scroll controller
primary	Whether to use the primary scroll view	Not set	True / false
physics	Scroll physics	Not set	bouncing, clamping, alwaysScrollable, rangeMaintaining, neverScrollable, page
shrinkWrap	Whether to shrink to fit the content size	true	True / false
padding	Inner padding	Not set	Padding value
mainAxisSpacing	Cell spacing along the main (scroll) axis	0	Number (minimum 0)
crossAxisSpacing	Cell spacing along the cross axis	0	Number (minimum 0)
childAspectRatio	Width-to-height ratio of a cell	2	Number (minimum 0.1)
addAutomaticKeepAlives	Whether to keep the state of items scrolled off screen	true	True / false
addRepaintBoundaries	Whether to add repaint boundaries	true	True / false
addSemanticIndexes	Whether to add semantic indexes	true	True / false
cacheExtent	Size of the area rendered ahead into the cache	Not set	Number
semanticChildCount	Number of semantic children	Not set	Number (integer)
dragStartBehavior	How the start of a drag is detected	start	down, start
keyboardDismissBehavior	How the keyboard is dismissed while scrolling	manual	manual, onDrag
restorationId	ID used to restore the scroll position	Not set	String
clipBehavior	How content outside the bounds is clipped	hardEdge	none, hardEdge, antiAlias, antiAliasWithSaveLayer
itemCount	Number of items to repeat	0	Number (integer)

Notes and tips

tip

Set crossAxisType to count and crossAxisCount drives the column count; set it to extent and maxCrossAxisExtent does. Change crossAxisType in the editor and the unused property is hidden automatically.

warning

Setting controller while primary is true is treated as an error, because the two cannot be used together. Use only one of them.

Learn more

tip

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