Masonry Grid

The Masonry Grid widget is designed for layouts where items have varying heights, such as image galleries, content cards, and mixed-media feeds. Unlike a regular GridView, which maintains straight rows, Masonry Grid focuses on filling vertical space efficiently by stacking items in columns with different heights.

This creates an organic, magazine-like layout where each column grows independently, minimizing empty gaps between items.

Core Concepts

1. Dynamic Children Only

The Masonry Grid is data-driven. You don’t manually drop multiple children inside it. Instead:

• You provide a JsonArray as the Data Source.

• You design one child widget template.

• Masonry Grid automatically repeats that template for each item in the array.

This is the same pattern as ListView and GridView:

• No static, individually-placed children

• Only dynamic content, generated from a data source

• Internally uses lazy building for performance

Note: If you need a fixed dashboard layout with precise manual placement, use a Column + Row, or Wrap instead. Masonry Grid is specifically designed for dynamic, data-driven content with variable heights.

2. Masonry Layout: Column-Based Flow

Masonry Grid arranges items into columns, not strict rows.

• Cross Axis (Columns) The number of columns is controlled by Cross Axis Count. For example, Cross Axis Count: 3 → 3-column masonry layout.

• Main Axis (Vertical Growth) Items are placed in the column with the current smallest height. This creates a staggered, Pinterest-like layout with minimal vertical gaps.

Key differences from GridView:

• GridView → row-based, rows are visually aligned.

• Masonry Grid → column-based, row lines are not aligned; each column grows at its own pace.

This makes Masonry ideal when:

• Items have different heights (e.g., different image aspect ratios, text lengths).

• You want a natural, flowing grid rather than strict, table-like rows.

3. Lazy Building & Performance

Like ListView and GridView with a data source, Masonry Grid uses lazy rendering:

• Only items that are visible (or about to become visible) are built.

• This allows you to display hundreds or thousands of items smoothly.

• Scrolling remains performant even with mixed-height content.

Performance Tip: For large masonry feeds, always bind to a Data Source and avoid putting heavy layouts inside each item template.

Data Source Property

The Data Source defines what the Masonry Grid displays and how many items it contains.

How to Configure the Data Source

1. In the properties panel, locate the Data Source field.

2. Provide a value that evaluates to a JsonArray.

You can configure this in two ways:

Option 1: Static JsonArray

Use a fixed JSON array:

[
  { "title": "Image 1", "url": "..." },
  { "title": "Image 2", "url": "..." }
]

Best for:

• Prototyping

• Simple demos or fixed, small sets of content

Option 2: Dynamic Expression

Bind the Data Source to an expression that returns a JsonArray:

• From an API response: ${apiResponse.data.images}

• From app state: ${appState.galleryItems}

• From a variable: ${masonryData}

When the underlying data changes, the Masonry Grid updates automatically.

Accessing Item Data with currentItem

Inside the item template, you can use:

• currentItem → The data for the current item.

• index → The zero-based index of the current item.

Examples:

• For objects: ${currentItem.imageUrl}, ${currentItem.title}, ${currentItem.height}

• For simple values: ${currentItem} (when the array contains strings, numbers, etc.)

Bind currentItem fields to images, text, badges, and other UI elements in your tile/card.

Important: The Data Source must be a JsonArray. If it’s not an array or expression is invalid, Masonry Grid will not render items.

Properties

Property	Description
Data Source	JsonArray of items to render. Each entry becomes one masonry tile using the child widget template.
Child Template	The single widget layout that is repeated for every item in the Data Source.
Cross Axis Count	Number of columns in the masonry grid (e.g. 2 or 3 for mobile layouts).
Main Axis Spacing	Vertical space (in pixels) between items stacked within the same column.
Cross Axis Spacing	Horizontal space (in pixels) between columns.
Padding / Margin	Optional outer spacing around the entire masonry grid container.
Allow Scroll	When true, the grid can be scrolled by the user. When false, scrolling is disabled.
Shrink Wrap	If true, the grid sizes itself to fit its children instead of expanding to fill available space.
Controller	Optional Scroll Controller variable used to programmatically control the scroll position.
Scroll Direction	Defines the axis along which the grid scrolls, typically vertical for masonry layouts.

Controller Integration

The Controller property allows you to programmatically control the Masonry Grid’s scroll behavior using a Scroll Controller variable.

How to Use a Scroll Controller

1. Create a Scroll Controller Variable

   • Go to Variables.

   • Add a new variable of type Scroll Controller.

   • Name it, e.g. masonryScrollController.

2. Bind the Controller to Masonry Grid

   • Select the Masonry Grid widget.

   • In the Controller property, set: ${masonryScrollController}

3. Control Scroll Position

   • Use the Control Object action to call methods on the controller:

     • jumpTo(...)

     • animateTo(...)

     • And other supported scroll methods

For complete details on controller methods, see the Variables documentation.

Tip:

The same controller can be used for:

• Programmatic scrolling

• Scroll-driven animations (e.g. fade on scroll, parallax) via Animation Builder.

Default Properties

The Masonry Grid widget supports all Default Properties.

Best Practices

• Use Masonry for uneven heights Ideal for image galleries, cards with varying text length, and content feeds.

• Choose Cross Axis Count carefully

  • 2 or 3 columns for mobile

  • More columns for tablets and larger screens

• Control item height via child Use aspect-ratio, images, or content length to define the natural height of each card.

• Handle empty states If the Data Source is empty, show a separate empty state message or placeholder.

• Avoid heavy layouts per item Keep your tile/card template lightweight for smooth scrolling.

• Use spacing wisely Add enough spacing to keep the grid readable, especially with text-heavy cards.

• Avoid nested scrolls in same direction Don’t put a vertical Masonry Grid inside another vertical scroll unless necessary and handled carefully.

Use Case

Use Case	Configuration Example
Pinterest-style Feed	Cross Axis Count: 2–3, variable-height image cards
Image Gallery	Cross Axis Count: 3, mixed aspect ratios
Blog / Article Cards	Cross Axis Count: 2, text + image cards
Inspiration Board	Cross Axis Count: 3, small padding + spacing
Mixed Media Grid	Cross Axis Count: 2, different widgets per item

Summary

Feature	Masonry Grid
Children Type	Dynamic only (requires a Data Source JsonArray).
Layout Behaviour	Column-based masonry layout with staggered rows and variable heights.
Best For	Pinterest-style feeds, image galleries, mixed-height cards, inspiration grids.
Performance	Lazy rendering (builds only visible items for smooth scrolling).
Layout Direction	2D grid; items arranged in columns, rows not visually aligned.
Scroll Control	Via Scroll Controller variable (jumpTo, animateTo, etc.).
Key Properties	Data Source, Cross Axis Count, Main Axis Spacing, Cross Axis Spacing, Controller, Allow Scroll, Shrink Wrap.