Build dynamic UI components with Repeaters

The Repeater component in Agent Builder allows you to display dynamic lists of data in your UI. It’s similar to the For-each loop block in blueprints, but for UI elements. This document provides an overview of Repeaters and how to use them in your Agent Builder agents with two examples.

Overview

A Repeater takes a list or dictionary and creates a copy of its child components for each item in that data. Inside the Repeater, you can access:

@{item}: the current item’s value
@{itemId}: the current item’s index, for arrays, or key, for dictionaries

Below is an example interface with a Repeater that displays a list of recipes based on user input. The Repeater is used to display each recipe in a tabbed layout and also to display the ingredients and steps for each recipe as nested text Repeaters.

Repeater demo that displays a list of recipes based on user input

See the tutorial below for more details about building this recipe generator.

When to use Repeaters

Repeaters are useful for displaying:

Lists of files, tasks, or messages
Search results or product catalogs
User-generated content like comments or reviews
Data from APIs or structured output
Any collection where you don’t know the exact number of items

Example: Display a list of items

This example starts with a small use case to dynamically display whatever a user selects from a select input.

To start, you should have a new Agent Builder agent and clear the demo agent so you can start from scratch. See the instructions for clearing the demo agent in the Agent Builder quickstart.

Set up the select input

The select input allows the user to select multiple items from a list. You’ll use it to select the items to display in the Repeater.

Add the select input to the agent

First, add a Select input block to the agent’s interface. This is the input that will be used to select the items to display in the Repeater.Update the following settings:

Label: Items
Under Options, add a few key-value pairs as options for the dropdown. For example:
- Key: Apple, Value: Apple
- Key: Berry, Value: Berry
- Key: Cherry, Value: Cherry
Link variable under Binding: list

When you define the options for the select input, the values are what the user sees in the select dropdown, and the keys are what will be stored in the state variable.

Add a Heading component

Add a Heading component to the agent’s interface. This separates the select input from the Repeater.Under Text, update the text to You selected:. Next, you’ll add the Repeater below this heading.

Add the Repeater

The Repeater displays a list of items dynamically. You’ll use it to display the items selected from the select input.

Add a Repeater component

Add a Repeater component to your page. Update the following settings:

Repeater object: @{list}. This is the list of items to display in the Repeater.

The Key variable name and the Value variable name default to itemId and item. These are the variable names you use to access the current item’s index and value within the Repeater. You can change them to anything you want. In this example, you’ll use the default names.

Add a Text component inside the Repeater

Drag a Text component inside the Repeater.Inside the text component, set the text to @{item} to display the value of the current item in the Repeater.When the list state variable is empty, the text displays placeholder text. When the user selects items from the multiselect input, the text displays the selected items.

Update the Repeater's visibility

Once you add components to a Repeater, you can no longer see the parent Repeater component in the agent’s interface view. You can find and edit the invisible component from the Interface Layers tab.

Navigate to the Interface Layers sidebar within the agent’s Interface tab. Then, click the Repeater component to open its configuration menu.Under Visibility in the Repeater’s configuration menu, select Custom. Set the condition to list. This ensures the Repeater is only visible when the user has selected at least one item from the select input and the list state variable isn’t empty.

Once you set a component’s visibility to become hidden, you can no longer see it or its children within the agent’s interface view. You can find and edit the invisible component from the Interface Layers tab.

Preview the Repeater

Navigate to the Preview tab to see the Repeater in action.Select a few items from the select input to see the Repeater display the corresponding items.

Tutorial: Build a recipe generator with Repeaters

This tutorial uses multiple Repeaters to display a list of recipes based on user input.

The recipe generator:

Accepts a list of dish names from the user
Generates complete recipes in the blueprint using AI structured output
Displays each recipe in an organized, tabbed layout using nested Repeaters

Part 1: Set up a minimal UI and the blueprint

First, you’ll set up a minimal UI and the blueprint. This UI won’t use any Repeaters yet, but it will be the foundation for the recipe generator.

Create the input interface

Add a Text Input

Add a Text Input to your page. Update the following settings:

Label: Recipes
Placeholder text: Enter dish names (e.g., "Pizza, Chocolate Chip Cookies, Tacos")
Link variable under Binding: request

Add a Button to trigger the blueprint

Add a Button to your page. Update the following settings:

Label: Get recipes

Build the blueprint

The blueprint contains three blocks:

UI Trigger to trigger the blueprint when a user clicks the Get recipes button
Structured Output block to generate the recipes and provide structured output that the Repeaters can use
Set State block to store the recipes in the state variable recipes

Add a UI Trigger block

Add a UI Trigger block to your blueprint. Update the following settings:

Component Id: Select the Get recipes button
Action: wf-click

Add a Structured Output block

Add a Structured Output block to your blueprint. Update the following settings:

Prompt:

You are a helpful cooking assistant. The user will provide you with a list of dish names. For each dish mentioned, create a complete recipe with the name, ingredients list, and step-by-step cooking instructions.

Guidelines:
- Provide practical, easy-to-follow recipes suitable for home cooking
- Include specific measurements for ingredients (cups, tablespoons, etc.)
- Write clear, numbered steps that a beginner could follow
- Keep recipes simple but complete
- If a dish name is vague, choose a popular/classic version of that dish

For each dish in the user's input, generate a separate recipe object with:
- name: The specific recipe name
- ingredients: A detailed list of all ingredients with measurements
- steps: Clear, sequential cooking instructions

Example input: "Pizza, Chocolate Chip Cookies"
This should generate recipes for both pizza and chocolate chip cookies.

Process all dishes mentioned in the user's input and provide complete recipes for each one.

User input: @{request}

JSON Schema: The JSON schema below defines the structure of the recipes as a list of recipe objects. Each recipe object has a name, ingredients, and steps. The Repeaters will use this schema to display the recipes.

{
  "type": "array",
  "description": "Array of recipe objects",
  "items": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "The name of the recipe"
      },
      "ingredients": {
        "type": "array",
        "description": "List of ingredients needed for the recipe",
        "items": {
          "type": "string"
        }
      },
      "steps": {
        "type": "array",
        "description": "Step-by-step cooking instructions",
        "items": {
          "type": "string"
        }
      }
    },
    "required": ["name", "ingredients", "steps"]
  }
}

Add a Set State block

Add a Set State block to your blueprint. Update the following settings:

State variable: recipes
Value: @{result}

The complete blueprint should look like this:

Test the blueprint

Now you can test that the blueprint works before you add the Repeaters. Navigate to the Preview tab to test the blueprint. Enter something like “Pizza, Chocolate Chip Cookies” in the text input and click the Get recipes button. You should see the request and the structured output in the result state variables in your state before moving to the next step.

Part 2: Add the main recipe Repeater

Navigate back to the Interface tab to continue building the recipe generator’s UI.

Add a Repeater component

Add a Repeater component to your page. Update the following settings:

Repeater object: @{recipes}. This is the list of recipes you stored in the recipes state variable.

Add a Heading component inside the Repeater

Add a Heading component inside the Repeater. Update the following settings:

Text: @{item.name}

This displays the name of each recipe as a heading.

If you preview the agent now, you should see a heading for each recipe name.

At this point, when there are no recipes, the Repeater still displays placeholder text. At the end of the tutorial you’ll update the Repeater to be invisible when there are no recipes.

Part 3: Add nested Repeaters for ingredients and steps

Now you’ll add nested Repeaters for ingredients and steps. You’ll use a Tab Container to display the ingredients and steps in separate tabs.

Add a Tab Container inside the main Repeater

Add a Tab Container inside the Repeater by dragging it into the space that contains the heading. You can verify that the tab container is inside the Repeater by checking the Interface Layers sidebar.

Create the first tab

Add a Tab component to the tab container. Update the following settings:

Tab name: “Ingredients”

Then drag a Repeater inside the tab. Update the following settings:

Repeater object: @{item.ingredients}

Add a Text component inside the first tab's Repeater

Add a Text component inside the first tab’s Repeater. Update the following settings:

Text: - @{item}

Create the second tab with a Repeater

Add a second Tab component to the tab container. Update the following settings:

Tab name: “Instructions”

Then drag a Repeater inside the tab. Update the following settings:

Repeater object: @{item.steps}

Add a Text component inside the second tab's Repeater

Add a Text component inside the second tab’s Repeater. Update the following settings:

Text: - @{item}

Update the Repeater's visibility

From the Interface Layers sidebar, click the first Repeater component, which contains the headings and tab components. Under Visibility in the main Repeater’s configuration menu, select Custom. Set the condition to recipes. This ensures the Repeater is only visible when the user has selected at least one recipe.

If you preview the agent now, you should see the ingredients and steps for each recipe in separate tabs. You also shouldn’t see the Repeater if there are no recipes.

Understanding nested Repeaters

In this tutorial, you used three different Repeaters:

Main Repeater: iterates over the recipes array (@{recipes})
Ingredients Repeater: iterates over each recipe’s ingredients array (@{item.ingredients}). This Repeater is nested inside the main Repeater.
Steps Repeater: iterates over each recipe’s steps array (@{item.steps})

Each Repeater creates its own @{item} context, so the inner Repeaters access individual ingredients and steps as @{item}, while the outer Repeater’s @{item} refers to the entire recipe object.

Next steps

Try extending this tutorial by:

Adding cooking time and difficulty level to the recipe schema
Styling the recipe cards with colors and spacing
Adding images or icons to make the recipes more visual
Creating filters to show only certain types of recipes

Getting started

Tutorials

Core concepts

User interface

Blueprints

Custom Python code

Local development

Interface block reference

Blueprint block reference

Build dynamic UI components with Repeaters

Overview

When to use Repeaters

Example: Display a list of items

Set up the select input

Add the Repeater

Tutorial: Build a recipe generator with Repeaters

Part 1: Set up a minimal UI and the blueprint

Create the input interface

Build the blueprint

Test the blueprint

Part 2: Add the main recipe Repeater

Part 3: Add nested Repeaters for ingredients and steps

Understanding nested Repeaters

Next steps

Getting started

Tutorials

Core concepts

User interface

Blueprints

Custom Python code

Local development

Interface block reference

Blueprint block reference

​Overview

​When to use Repeaters

​Example: Display a list of items

​Set up the select input

​Add the Repeater

​Tutorial: Build a recipe generator with Repeaters

​Part 1: Set up a minimal UI and the blueprint

​Create the input interface

​Build the blueprint

​Test the blueprint

​Part 2: Add the main recipe Repeater

​Part 3: Add nested Repeaters for ingredients and steps

​Understanding nested Repeaters

​Next steps

Overview

When to use Repeaters

Example: Display a list of items

Set up the select input

Add the Repeater

Tutorial: Build a recipe generator with Repeaters

Part 1: Set up a minimal UI and the blueprint

Create the input interface

Build the blueprint

Test the blueprint

Part 2: Add the main recipe Repeater

Part 3: Add nested Repeaters for ingredients and steps

Understanding nested Repeaters

Next steps