## Repeater Component

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](https://dev.writer.com/blueprints/for-eachloop) 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.

See the [tutorial](https://dev.writer.com/agent-builder/repeater#tutorial%3A-build-a-recipe-generator-with-repeaters) 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](https://dev.writer.com/agent-builder/quickstart#clear-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.

1. **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.

2. **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.

1. **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.

2. **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.

3. **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.

4. **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.

1. **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`

2. **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`

1. **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`

2. **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**:
        
        ```
        {
            "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"]
            }
        }
        ```

3. **Add a Set State block**  
   Add a **Set State** block to your blueprint. Update the following settings:
   - **State variable**: `recipes`
   - **Value**: `@{result}`

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

1. **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.

2. **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.

### Part 3: Add nested Repeaters for ingredients and steps

1. **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.

2. **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}`

3. **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}`

4. **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}`

5. **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}`

6. **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.