# 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. {% embed url="" %} Watch this on Youtube: ### 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.
A diagram showing the main and cross axis of a Wrap widget.

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
PropertyDescription
DirectionDetermines the primary axis for laying out children. Horizontal arranges them in rows, while Vertical arranges them in columns.
AlignmentDefines 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 AlignmentDefines 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 AlignmentDefines 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.
SpacingThe amount of empty space to place between each child along the main axis.
Run SpacingThe 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.
An image showing horizontal alignment in a Wrap widget.

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

An image showing vertical alignment in a Wrap widget.

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.
An image showing horizontal run alignment in a Wrap widget.

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

An image showing vertical run alignment in a Wrap widget.

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.
An image showing spacing between children in a Wrap widget.

The Spacing property adds space between children along the run axis

An image showing spacing between runs in a Wrap widget.

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.
An image showing CrossAxisAlignment for children in a Horizontal wrap.

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

An image showing CrossAxisAlignment for children in a Vertical 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](https://docs.digia.tech/ui-building-blocks/widgets/default-properties "mention"). ### 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