MasonryGrid
The MasonryGrid widget is a staggered grid that packs tiles of varying heights together with no gaps.
Use it to arrange content whose items differ in height — like a gallery of cards — across multiple columns.
This widget is locked on the Free plan. It's available on the Pro and Enterprise plans.
Definition and role
The MasonryGrid widget splits its child items across the number of columns you set in crossAxisCount, then stacks them tightly from the top to match each tile's height. Unlike a regular grid, tiles fill the space without gaps even when their heights vary. Items repeat as many times as the data count (itemCount), using one repeated child as the template.
- Category: Layouts
- Size when dropped: inside a parent layout (Row, Column, Stack, and so on) it starts at
200 x 150. Placed at the top level with no parent, it appears larger to fill the canvas.
Features
| Feature | Description |
|---|---|
| Staggered layout | Packs tiles tightly from the top with no gaps, even when their heights differ. |
| Column count | Set how many columns sit in one row (the cross axis) with crossAxisCount. |
| Item repetition | Renders the child item itemCount times. |
| Spacing control | Adjust the vertical and horizontal gaps between tiles with mainAxisSpacing and crossAxisSpacing. |
| Scroll settings | Set the scroll direction (scrollDirection), reverse order (reverse), physics (physics), and more. |
How to use
- Open the Layouts category in the left widget palette.
- Drag and drop the MasonryGrid item onto the canvas.
- In the Properties panel on the right, set the column count with
crossAxisCount. - Set how many items to repeat with
itemCount, then build the child widget that repeats. - If needed, adjust the tile gaps with
mainAxisSpacingandcrossAxisSpacing.
Properties
| Property | Description | Default | Value / Type |
|---|---|---|---|
scrollDirection | Scroll (layout) direction | vertical | horizontal, vertical |
reverse | Reverse the order items are laid out in | Off (false) | true / false |
controller | Scroll controller to attach | Not set | Scroll controller |
primary | Whether to use this as the primary scroll view | Not set | true / false |
physics | Scroll physics | Not set | Scroll physics value |
shrinkWrap | Shrink the layout to fit its content | On (true) | true / false |
padding | Padding inside the grid | Not set | Inset value |
crossAxisCount | Number of columns in one row (the cross axis) | 1 | Number (1 or higher) |
mainAxisSpacing | Tile gap along the main axis (vertical) | 0 | Number (0 or higher) |
crossAxisSpacing | Tile gap along the cross axis (horizontal) | 0 | Number (0 or higher) |
itemCount | Number of items to generate | 0 | Number |
addAutomaticKeepAlives | Keep the state of off-screen items | On (true) | true / false |
addRepaintBoundaries | Add a repaint boundary to each item | On (true) | true / false |
addSemanticIndexes | Give each item a semantic index | On (true) | true / false |
cacheExtent | Size of the cache area rendered ahead | Not set | Number |
semanticChildCount | Number of semantic children | Not set | Number |
dragStartBehavior | What counts as the start of a drag | start | down, start |
keyboardDismissBehavior | How the keyboard closes while scrolling | manual | manual, onDrag |
restorationId | ID for restoring the scroll position | Not set | String |
clipBehavior | How children are clipped | hardEdge | none, hardEdge, antiAlias, antiAliasWithSaveLayer |
Notes and tips
Set crossAxisCount to 1 or higher. The larger the value, the more columns fit in a single row.
shrinkWrap defaults to true, so the grid takes up only as much height as its content. That's useful when you place it inside another scrolling area.
Learn more
For the full Widget Control (Property, Method, Event) you can use to drive this widget from a script, visit MasonryGrid Widget Control.