Wrap
The Wrap widget is a powerful layout component that arranges its children in a horizontal or vertical sequence, automatically "wrapping" them to the next line when there isn't enough space. This is incredibly useful for creating responsive layouts with a variable number of items, such as a list of tags, a photo gallery, or a set of filter chips.
Core Concepts
1. Axis and Wrapping
Unlike Row or Column, which force children into a single line, Wrap is flexible. It attempts to lay out children along its main axis (Direction) and, if it runs out of room, it simply moves to the next line on the cross axis.
Direction: The primary axis along which children are placed. This can be
Horizontal(like aRow) orVertical(like aColumn).Wrapping: When children overflow the available space on the main axis, they wrap onto a new "run" on the cross axis.
2. Dynamic Children
Similar to Row and Column, the Wrap widget is perfect for displaying dynamic data. By connecting it to a Data Source, you can generate a list of child widgets from a JsonArray. This makes it ideal for rendering lists of tags, user-selected choices, or any collection of items where the count is not fixed.
Properties
Layout & Spacing
Direction
Determines the primary axis for laying out children. Horizontal arranges them in rows, while Vertical arranges them in columns.
Alignment
Defines how children are positioned along the main axis (e.g., Start, Center, End, Space Between). This is similar to Main Axis Alignment in a Row/Column.
Run Alignment
Defines how the "runs" (the lines of wrapped children) are distributed along the cross axis. For example, if you have a Horizontal wrap with two lines of children, Run Alignment controls the vertical spacing between those lines.
Cross Axis Alignment
Defines how children within the same run are aligned relative to each other along the cross axis. For example, in a Horizontal wrap, this controls whether taller and shorter children align to the top, center, or bottom of their line.
Spacing
The amount of empty space to place between each child along the main axis.
Run Spacing
The amount of empty space to place between each run along the cross axis. For a Horizontal wrap, this is the vertical gap between lines.
Alignment in horizontal and vertical
The alignment property is used to align the children in the main axis.
Alignment property controlling the horizontal distribution of children in a Horizontal wrap.
Alignment property controlling the vertical distribution of children in a Vertical wrap.RunAlignment in horizontal and vertical
The runAlignment property is used to align the runs in the cross axis.
RunAlignment property controlling the vertical distribution of runs in a Horizontal wrap.
RunAlignment property controlling the horizontal distribution of runs in a Vertical wrap.Spacing and RunSpacing
The spacing and runSpacing properties are used to add space between the children and runs respectively.
Spacing property adds space between children along the run axis
RunSpacing property adds space between runs.CrossAxisAlignment in horizontal and vertical
CrossAxisAlignment is used to align the children relative to each other in the cross axis.
CrossAxisAlignment property controlling the vertical alignment of children within a run in a Horizontal wrap.
CrossAxisAlignment property controlling the horizontal alignment of children within a run in a Vertical wrap.Children: Static vs. Dynamic
You can populate a Wrap widget with child widgets in two ways:
1. Static Children
Add a fixed number of child widgets directly in the builder. Each child you add will appear in the widget tree, and its properties can be configured individually. This is ideal for layouts where the number of items is known and doesn't change.
2. Dynamic Children
To generate children from a list of data, you can use the Data Source property. This turns the Wrap widget into a powerful list builder.
Enable the
Data Sourcetoggle in the properties panel.Provide data by either entering a fixed
JsonArrayin the JSON editor or binding it to an expression that returns aJsonArray(e.g., from an API call or App State).Add a single child widget to the
Wrap. This widget acts as a template that will be repeated for each item in the data source.Inside this template child, use the
currentItemvariable to access the data for each item.If your data is a list of objects (e.g.,
[{"name": "Apple"}, {"name": "Banana"}]), access properties with dot notation:${currentItem.name}.If your data is a list of simple values (e.g.,
["Apple", "Banana"]),currentItemrefers to the value itself:${currentItem}.
This is perfect for building a dynamic list of filter chips, product tags, or any other repeating UI element that needs to wrap gracefully.
Use Cases
The Wrap widget is ideal for:
Tagging Systems: Displaying a list of tags on a blog post or product page.
Filter Chips: Showing a set of selectable filter chips in a search interface.
User Avatars: Arranging a collection of user avatars that can grow or shrink.
Responsive Menus: Creating a horizontal menu that wraps into multiple lines on smaller screens.
Image Galleries: Displaying a collection of images that wrap to the next line.
Default Properties
The Wrap widget supports all Default Properties, such as Visibility, Padding, Margin, and Background Color.
Last updated