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.

Watch this on Youtube: https://www.youtube.com/watch?v=haYNAaamK18

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 a Row) or Vertical (like a Column).

• Wrapping: When children overflow the available space on the main axis, they wrap onto a new "run" on the cross axis.

Example of a Wrap widget where items wrap to a new line.

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

Property	Description
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.

The Alignment property controlling the horizontal distribution of children in a Horizontal wrap.

The 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.

The RunAlignment property controlling the vertical distribution of runs in a Horizontal wrap.

The 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.

The Spacing property adds space between children along the run axis

The 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.

The CrossAxisAlignment property controlling the vertical alignment of children within a run in a Horizontal wrap.

The 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.

1. Enable the Data Source toggle in the properties panel.

2. Provide data by either entering a fixed JsonArray in the JSON editor or binding it to an expression that returns a JsonArray (e.g., from an API call or App State).

3. 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.

4. Inside this template child, use the currentItem variable 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"]), currentItem refers 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.

---

Default Properties

The Wrap widget supports all Default Properties.

Use Cases

The Wrap widget is used when items need to automatically move to the next line instead of overflowing.

Use Wrap when you want to:

• Display chips or tags

  • Filters, categories, interests, labels that may be many in number

  • They should wrap onto the next line when they don’t fit in one row

• Responsive pill / button groups

  • Small buttons, shortcuts, or options that should flow naturally on small and large screens

• Inline icon/text groups that wrap

  • Badges, info pills, or small cards that shouldn’t require horizontal scrolling