Skip to content

Iterating Over Data

Overview

The Iterate property lets you repeat any component or HTML element for each item in an array. Configure it once on the parent element, and Bellini automatically renders one instance per item, making it the standard pattern for displaying dynamic lists, tables, cards, and menus.

What You Will Learn

  • How the Iterate property works and when to use it
  • How to configure iteration using Array Name and Variable Name
  • How to reference the current item variable in child component expressions
  • Common patterns for rendering API-driven lists and filtered data

When To Use This

Use this when you need to display a list of items from an array — such as products, orders, or users — by repeating a component for each item.

How Iterating Works

When you set the Iterate property on a component, Bellini renders one copy of that component for each item in the array you specify. Each copy has access to a current item variable that holds the corresponding array element. You use this variable in the expressions of that component and any of its children to display or interact with item-specific data.

The component itself is the template — it is rendered once per array item, not once in total.

Configuring the Iterate Property

Select the component or element you want to repeat, then open the Properties view in the right sidebar. Find the Iterate property (in the Common category) and expand it to reveal the configuration fields:

Field Description
Array Name An expression that resolves to the array to iterate over. Example: $ctrl.orders
Variable Name The name to use for the current item in each iteration. Example: order
Track by Index When enabled, Bellini tracks items by their position in the array instead of by identity. Use this when array items do not have a stable unique identifier.

After setting these fields, the component is repeated for each item in the array.

Shortcut — drag and drop from Declarations: You can also drag an array declaration from the Declarations panel and drop it directly onto the Iterate property in the Properties view. Bellini automatically populates Array Name with the reference to that declaration and sets a default Variable Name based on the declaration name.

Using the Item Variable in Expressions

Once configured, the variable name you set in Variable Name becomes available in the expressions of the iterated component and all of its children. Reference it directly — without a $ctrl. prefix — in any expression within that scope.

For example, if Variable Name is order:

1
order.customerName

1
order.total * 1.1

1
order.status === 'shipped'

The variable is only in scope within the iterated component and its children. Components outside the iteration cannot reference it.

Using Nested Components

Child components placed inside an iterated component inherit the item variable. This lets you build composite rows with multiple bindings all referencing the same item.

For example, a Card component iterated over $ctrl.products (Variable Name: product) might contain:

  • A Text component with its Text property set to product.name
  • An Image component with its Source property set to product.imageUrl
  • A Button component with its Click handler calling $ctrl.selectProduct(product)

Each rendered card automatically uses the data from its corresponding array item.

Common Patterns

Rendering a list from an API service

The recommended pattern is to use a function declaration with Invoke on Load enabled to fetch data on page load and store it in an array declaration. Then iterate a component over that declaration:

  1. In Declarations, create an array declaration (e.g., products) to hold the data.

  2. Create a function declaration (e.g., loadProducts), enable Invoke on Load, and write the function body to call the API and assign the result:

    1
    $ctrl.myProductApi.listProducts().then(response => $ctrl.products = response.data);

  3. Select the component to repeat and set Array Name to:

    1
    $ctrl.products

  4. Set Variable Name to product.

  5. In child components, use product.fieldName expressions to display each item's data.

Filtering the displayed items

To display only a subset of the array, store the filtered items in a dedicated array declaration and iterate over that. A function with Invoke on Load (or triggered by a filter input) computes the filtered result and assigns it:

  1. In Declarations, create an array declaration to hold the filtered results (e.g., activeProducts).

  2. Create a function declaration (e.g., filterProducts) that filters the source array and assigns the result:

    1
    $ctrl.activeProducts = $ctrl.products.filter(p => p.isActive);

  3. Set Array Name on the iterated component to:

    1
    $ctrl.activeProducts

Call filterProducts on load (via Invoke on Load) or in response to user input to refresh the filtered list.

Passing the current item to a function

Event handler expressions can pass the current item variable as an argument to a function:

1
$ctrl.openDetail(order)

1
$ctrl.deleteItem(item.id)

Track by Index

By default, Bellini tracks each rendered instance by the identity of the array item. If two items are equal in value (or the array is reconstructed on each update), the UI may re-render more than necessary.

Enable Track by Index to track by array position instead. This is useful when:

  • Array items are plain objects without unique identifiers
  • The array is reconstructed from an API response on every call
  • You experience unexpected re-renders or focus loss in list inputs

Avoid enabling this when the array order can change — tracking by index will cause incorrect rendering if items are reordered.

Helpful Resources