GridView

A powerful widget for displaying items in a scrollable 2D grid layout.

The GridView widget is a layout widget designed for displaying items in a scrollable, two-dimensional grid. It's perfect for photo galleries, product catalogs, dashboards, and any interface that requires items to be arranged in rows and columns.

Unlike ListView, which displays items in a single direction, GridView arranges items both horizontally and vertically, creating a table-like structure.

The GridView widget works exactly like Flutter's GridView.builder. For an in-depth technical understanding, you can refer to the official Flutter GridView documentation.

Core Concepts

1. Dynamic Children Only

The GridView widget requires a data source to function. You cannot add static children individually in the builder. Instead, you provide a JsonArray of data, and GridView automatically repeats a single child widget template for each item in that array.

This is fundamentally the same as ListView—GridView is purpose-built for data-driven grids and uses lazy rendering to efficiently display large datasets.

Note: If you need a fixed grid layout with specific, hand-placed widgets (like a dashboard), use a Column with Row widgets inside, or use Wrap widget instead. GridView is designed exclusively for dynamic, data-driven content.

2. Grid Structure: Rows & Columns

GridView arranges items in a grid defined by:

• Cross Axis (Columns): The number of items per row, controlled by Cross Axis Count.

• Main Axis (Rows): The vertical flow direction. Items wrap to a new row when the cross axis count is reached.

For example, with Cross Axis Count: 3, items are arranged in rows of 3 columns each.

GridView flows items from left to right, wrapping to new rows based on Cross Axis Count.

3. Lazy Building & Performance

When using a data source, GridView uses lazy rendering—it only builds grid items as they scroll into view. This makes it highly performant for displaying hundreds or thousands of items without impacting app performance.

Performance Tip: For large grids with dynamic data, always use the Data Source property. GridView will only render visible items, keeping your app fast and responsive.

---

Data Source Property

The Data Source is the most critical property of GridView. It determines what data the grid will display and how many items it will contain.

How to Configure the Data Source

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

2. You can provide data in two ways:

Option 1: Static JsonArray

Enter a fixed JSON array directly:

[
  {"name": "Product 1", "image": "url1.jpg", "price": 29.99},
  {"name": "Product 2", "image": "url2.jpg", "price": 39.99},
  {"name": "Product 3", "image": "url3.jpg", "price": 19.99}
]

This is useful for prototyping or displaying a small, unchanging grid.

Option 2: Dynamic Expression

Bind the data source to an expression that returns a JsonArray:

• From an API Response: ${apiResponse.data.products}

• From App State: ${appState.galleryImages}

• From a Variable: ${myGridData}

The GridView will automatically update whenever the data source changes.

Accessing Item Data with currentItem

When using a data source, inside the child template you have access to:

• currentItem: The data for the current grid item being rendered.

  • For objects: ${currentItem.name}, ${currentItem.price}

  • For simple values: ${currentItem}

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

Use currentItem to bind data to your grid item template.

Important: When using a Data Source, it must be a JsonArray. If you bind it to a non-array value or an invalid expression, the GridView will not render any items.

---

Properties

Grid Layout

Property	Description
Cross Axis Count	(Required) The number of columns in the grid. This determines how many items appear per row. For example, 3 creates a 3-column grid.
Main Axis Spacing	The vertical space between rows in pixels. Controls the gap between items stacked vertically.
Cross Axis Spacing	The horizontal space between columns in pixels. Controls the gap between items placed side-by-side.

Use spacing properties to control gaps between grid items.

Scrolling Behavior

Property	Description
Controller	An optional Scroll Controller variable to programmatically control the scroll position. Learn how to create and use scroll controllers in the Variables documentation.
Allow Scroll	If true, the grid will be scrollable. If false, scrolling is disabled. Default is true.
Shrink Wrap	If true, the GridView will size itself to fit its children instead of expanding to fill available space. Useful when nesting inside another scrollable widget, but use with caution as it can impact performance.

Controller Integration

The Controller property allows you to programmatically control the scroll position of the GridView. This is done by creating a Scroll Controller variable and binding it to the GridView.

How to Use a Scroll Controller

1. Create a Scroll Controller Variable

   • Navigate to Variables in your project.

   • Add a new variable of type Scroll Controller.

   • Give it a name, such as gridScrollController.

2. Bind the Controller to the GridView

   • Select the GridView widget.

   • In the Controller property, enter an expression referencing your variable: ${gridScrollController}.

3. Control the Scroll Position

   • Use the Control Object action to invoke methods on the controller (such as jumpTo, animateTo, etc.).

   • For a complete list of available controller methods and their usage, see the Variables documentation.

Tip: You can use the same controller for both programmatic scrolling (via Control Object actions) and scroll-driven animations (via Animation Builder).

---

Guides

For detailed step-by-step tutorials on common GridView patterns, see:

GridView Animation BuilderGridView Multiple Item Types

---

Default Properties

The GridView widget supports all Default Properties.

---

Best Practices

• Choose the right Cross Axis Count for your content and screen size. Too many columns can make items too small; too few can waste space.

• Control item sizing through the child widget template dimensions.

• Optimize item templates to ensure smooth scrolling performance, especially for large grids.

• Handle empty states gracefully with clear messaging when no data is available.

• Use spacing properties to create visual breathing room between items.

• Consider responsive design: For different screen sizes, you might want to adjust Cross Axis Count dynamically.

• Avoid nesting scrollable widgets in the same direction to prevent scroll conflicts.

---

Common Use Cases

Use Case	Configuration Example
Photo Gallery	Cross Axis Count: 3, with image URLs in data
Product Catalog	Cross Axis Count: 2, with product data
Category Grid	Cross Axis Count: 2, with category data
Icon Grid	Cross Axis Count: 4, small spacing
Featured Items Grid	Cross Axis Count: 2, with mixed content

---

Summary

GridView is the ideal widget for creating scrollable, data-driven grid layouts. By requiring a data source and rendering items lazily, it ensures smooth performance even with large datasets of images, products, or other content.

Feature	GridView
Children Type	Dynamic only (requires Data Source)
Performance	Lazy rendering (builds items on-demand)
Best For	Photo galleries, product grids, category lists
Layout Direction	2D grid (rows and columns)
Scroll Control	Via Scroll Controller
Heterogeneous Support	Yes (using Conditional Builder as child)
Key Properties	Cross Axis Count, spacing, shrink wrap