WrapList
The WrapList widget is a repeating layout that lays items out in one direction and wraps them onto the next line when it runs out of space.
It works well when you have many items of different sizes and want to show them as a scrollable list.
Definition and role
WrapList renders a data list repeatedly, laying each item out along the layout direction — horizontal or vertical — and wrapping automatically when space runs out. Set maxLines to clip the items beyond that number of lines; WrapList then reports the number of clipped items (overflowCount) and the current line count (lineCount) through events.
- Category: Layouts
- Default layout direction:
horizontal - Size on drop: dropped inside a parent layout such as Row, Column, or Stack, it starts at
200 x 150. Dropped at the top level with no parent, it grows to fill the remaining space.
Features
| Feature | Description |
|---|---|
| Repeated layout | Renders each entry in the data list as a repeated child widget. |
| Automatic wrapping | Moves items to the next line when they no longer fit on the current one. |
| Spacing control | Set item spacing (spacing) and line spacing (runSpacing) separately. |
| Alignment | Set main-axis (alignment), run (runAlignment), and cross-axis (crossAxisAlignment) alignment. |
| Line limit | Limit the number of visible lines with maxLines, and report the number of clipped items through an event. |
How to use
- Open the Layouts category in the left widget palette.
- Drag the WrapList item onto the canvas.
- In the Properties panel on the right, set how many items to repeat using data binding or
itemCount. - Place the child widgets you want to repeat inside it.
- Adjust the layout direction, spacing, alignment,
maxLines, and other settings as needed.
Properties
| Property | Description | Default | Value / Type |
|---|---|---|---|
direction | Item layout direction | horizontal | horizontal, vertical |
alignment | Item alignment along the main axis | start | start, end, center, spaceBetween, spaceAround, spaceEvenly |
spacing | Spacing between items on the same line (main axis) | 0 | Number (px) |
runAlignment | Alignment of the runs (cross axis) | start | start, end, center, spaceBetween, spaceAround, spaceEvenly |
runSpacing | Spacing between one line and the next (cross axis) | 0 | Number (px) |
crossAxisAlignment | Cross-axis alignment of items within a line | start | start, end, center |
textDirection | Horizontal direction the main axis advances in | Not set | rtl, ltr |
verticalDirection | Vertical direction the lines stack in | down | up, down |
clipBehavior | How content outside the area is clipped | none | none, hardEdge, antiAlias, antiAliasWithSaveLayer |
itemCount | Number of items to repeat | 0 | Number |
maxLines | Maximum number of lines to show (Not set = unlimited = no clipping) | Not set | Number |
reservedTrailingExtent | Main-axis width to reserve at the end of the last line when maxLines is set — room for a "+N" badge, for example | Not set | Number (px) |
Notes and tips
Leave maxLines unset — the default — and WrapList shows every item with no line limit. In that state, overflowCount and lineCount are not updated.
Connect the data list you want to repeat in the Data Binding panel at the top, not in the Properties panel. If you only need a fixed count, set itemCount instead.
overflowCount and lineCount are read-only output values that don't appear in the Properties panel. Read them from a script or through data binding.
Learn more
For the full set of Widget Controls (Property, Method, and Event) that drive this widget from a script, visit WrapList Widget Control.