ListView

The ListView widget is a specialized layout widget designed for displaying scrollable lists efficiently. Unlike Row and Column, which can display both static and dynamic children, ListView is exclusively for dynamic, data-driven lists. It renders items lazily as they scroll into view, making it ideal for long or infinite lists.

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

Use Cases

Use ListView when you need a scrollable list of widgets, especially when the number of items can grow.

You’ll typically use ListView for:

• Scrollable content lists

  • Product lists, order history, notifications, messages

  • Settings options, menu items, FAQ entries

• Dynamic / API-driven lists

  • Data coming from an API, database, or backend

  • Infinite / long lists that the user can scroll through

• Repeatable item layouts

  • Same card design repeated for each item (e.g., blog posts, users, categories)

Core Concepts

1. Dynamic Children Only

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

This is fundamentally different from Row and Column, which support both static and dynamic children. ListView is purpose-built for data-driven lists.

2. Single Item Type vs. Multiple Item Types

ListView can handle two types of lists:

• Single Item Type (Uniform Lists): All items have the same structure and appearance. For example, a list of user profiles where each item displays a name, avatar, and bio in the same uniform layout.

  This is the most common use case and is what you'll configure with a single child template.

• Multiple Item Types (Varied Lists): Items can have different structures. For example, a social media feed where some items are text posts, some are image posts, and some are ads—creating a varied mix of content types.

  To build lists with varied item types, use a Conditional Builder as the child of the ListView. Inside the Conditional Builder, check the item type using currentItem and render different widgets accordingly.

3. Lazy Building & Performance

One of the key advantages of ListView is lazy rendering. Unlike Row or Column, which build all their children at once (even if they're off-screen), ListView only builds items as they scroll into view. This makes it highly performant for displaying hundreds or thousands of items.

Performance Tip: For long scrollable lists, always use ListView instead of a scrollable Row or Column with dynamic children. ListView is optimized for this use case and will prevent performance bottlenecks.

---

Data Source Property

The Data Source is the most critical property of ListView. It determines what data the list 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": "Apple", "price": 1.5},
  {"name": "Banana", "price": 0.8},
  {"name": "Orange", "price": 1.2}
]

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

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.userList}

• From a Variable: ${myListVariable}

The ListView will automatically update whenever the data source changes.

Accessing Item Data with currentItem

Inside the child template of the ListView, you have access to a special variable called currentItem. This variable represents the data for the current item being rendered.

• If your data is a list of objects (e.g., [{"name": "Apple"}, {"name": "Banana"}]), access properties using dot notation: ${currentItem.name}.

• If your data is a list of simple values (e.g., ["Apple", "Banana"]), use ${currentItem} directly.

You can also access the current index using ${index}.

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

---

Properties

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 list will be scrollable. If false, scrolling is disabled. Default is true.
Scroll Direction	The direction in which the list scrolls. Can be Vertical (default) or Horizontal.
Reverse	If true, reverses the order in which items are displayed. For vertical lists, the first item appears at the bottom instead of the top. For horizontal lists, the first item appears on the right instead of the left. The scroll direction remains the same.
Initial Scroll Position	The initial position of the scroll view when the list loads. Can be Start (default) or End.

Layout & Sizing

Property	Description
Shrink Wrap	If true, the ListView will size itself to fit its children instead of expanding to fill the available space. This is useful when nesting a ListView 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 ListView. This is done by creating a Scroll Controller variable and binding it to the ListView.

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

2. Bind the Controller to the ListView

   • Select the ListView widget.

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

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 ListView patterns, see:

ListView Animation BuilderListView Multiple Item Types

---

Default Properties

The ListView widget supports all Default Properties.

---

Best Practices

• Always provide a valid JsonArray as the data source. ListView will not render without it.

• Use ListView for long lists. For short, fixed lists (fewer than 10 items), a Column with dynamic children may be simpler, but ListView is still recommended for consistency and future scalability.

• Avoid nesting scrollable widgets in the same direction (e.g., a vertical ListView inside a vertical scrollable Column). This can cause unexpected scrolling behavior. If you must nest, use Shrink Wrap carefully.

• Optimize item templates. Keep the child template as lightweight as possible to ensure smooth scrolling performance.

• Handle empty states gracefully. Always provide feedback when the list has no data to display.

• Use Scroll Controllers when you need programmatic scroll control, such as "scroll to top" buttons or scroll-driven UI changes.