sim/apps/docs/content/docs/en/blocks/loop.mdx

---
title: Loop
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
import { Image } from '@/components/ui/image'

The Loop block is a container that executes blocks repeatedly. Iterate over collections, repeat operations a fixed number of times, or continue while a condition is met.

<Callout type="info">
  Loop blocks are container nodes that hold other blocks inside them. The contained blocks execute multiple times based on your configuration.
</Callout>

## Configuration Options

### Loop Type

Choose between four types of loops:

<Tabs items={['For Loop', 'ForEach Loop', 'While Loop', 'Do-While Loop']}>
  <Tab>
    **For Loop (Iterations)** - A numeric loop that executes a fixed number of times:
    
    <div className="flex justify-center">
      <Image
        src="/static/blocks/loop-1.png"
        alt="For Loop with iterations"
        width={500}
        height={400}
        className="my-6"
      />
    </div>
    
    Use this when you need to repeat an operation a specific number of times.
    
    ```
    Example: Run 5 times
    - Iteration 1
    - Iteration 2
    - Iteration 3
    - Iteration 4
    - Iteration 5
    ```
  </Tab>
  <Tab>
    **ForEach Loop (Collection)** - A collection-based loop that iterates over each item in an array or object:
    
    <div className="flex justify-center">
      <Image
        src="/static/blocks/loop-2.png"
        alt="ForEach Loop with collection"
        width={500}
        height={400}
        className="my-6"
      />
    </div>
    
    Use this when you need to process a collection of items.
    
    ```
    Example: Process ["apple", "banana", "orange"]
    - Iteration 1: Process "apple"
    - Iteration 2: Process "banana"
    - Iteration 3: Process "orange"
    ```
  </Tab>
  <Tab>
    **While Loop (Condition-based)** - Continues executing while a condition evaluates to true:
    
    <div className="flex justify-center">
      <Image
        src="/static/blocks/loop-3.png"
        alt="While Loop with condition"
        width={500}
        height={400}
        className="my-6"
      />
    </div>
    
    Use this when you need to loop until a specific condition is met. The condition is checked **before** each iteration.

    ```
    Example: While {"<variable.i>"} < 10
    - Check condition → Execute if true
    - Inside loop: Increment {"<variable.i>"}
    - Inside loop: Variables assigns i = {"<variable.i>"} + 1
    - Check condition → Execute if true
    - Check condition → Exit if false
    ```
  </Tab>
  <Tab>
    **Do-While Loop (Condition-based)** - Executes at least once, then continues while a condition is true:
    
    <div className="flex justify-center">
      <Image
        src="/static/blocks/loop-4.png"
        alt="Do-While Loop with condition"
        width={500}
        height={400}
        className="my-6"
      />
    </div>
    
    Use this when you need to execute at least once, then loop until a condition is met. The condition is checked **after** each iteration.

    ```
    Example: Do-while {"<variable.i>"} < 10
    - Execute blocks
    - Inside loop: Increment {"<variable.i>"}
    - Inside loop: Variables assigns i = {"<variable.i>"} + 1
    - Check condition → Continue if true
    - Check condition → Exit if false
    ```
  </Tab>
</Tabs>

## How to Use Loops

### Creating a Loop

1. Drag a Loop block from the toolbar onto your canvas
2. Configure the loop type and parameters
3. Drag other blocks inside the loop container
4. Connect the blocks as needed

### Referencing Loop Data

There's an important distinction between referencing loop data from **inside** vs **outside** the loop:

<Tabs items={['Inside the Loop', 'Outside the Loop']}>
  <Tab>
    **Inside the loop**, use `<loop.>` references to access the current iteration context:
    
    - **`<loop.index>`**: Current iteration number (0-based)
    - **`<loop.currentItem>`**: Current item being processed (forEach only)
    - **`<loop.items>`**: Full collection being iterated (forEach only)
    
    ```
    // Inside a Function block within the loop
    const idx = <loop.index>;           // 0, 1, 2, ...
    const item = <loop.currentItem>;    // Current item
    ```
    
    <Callout type="info">
      These references are only available for blocks **inside** the loop container. They give you access to the current iteration's context.
    </Callout>
  </Tab>
  <Tab>
    **Outside the loop** (after it completes), reference the loop block by its name to access aggregated results:
    
    - **`<LoopBlockName.results>`**: Array of results from all iterations
    
    ```
    // If your loop block is named "Process Items"
    const allResults = <processitems.results>;
    // Returns: [result1, result2, result3, ...]
    ```
    
    <Callout type="info">
      After the loop completes, use the loop's block name (not `loop.`) to access the collected results. The block name is normalized (lowercase, no spaces).
    </Callout>
  </Tab>
</Tabs>

## Example Use Cases

**Processing API Results** - ForEach loop processes customer records from an API
```
API (Fetch) → Loop (ForEach) → Agent (Analyze) → Function (Store)
```

**Iterative Content Generation** - For loop generates multiple content variations
```
Loop (5x) → Agent (Generate) → Evaluator (Score) → Function (Select Best)
```

**Counter with While Loop** - While loop processes items with counter
```
Variables (i=0) → Loop (While i<10) → Agent (Process) → Variables (i++)
```

## Advanced Features

### Limitations

<Callout type="warning">
  Container blocks (Loops and Parallels) cannot be nested inside each other. This means:
  - You cannot place a Loop block inside another Loop block
  - You cannot place a Parallel block inside a Loop block
  - You cannot place any container block inside another container block
  
  If you need multi-dimensional iteration, consider restructuring your workflow to use sequential loops or process data in stages.
</Callout>

<Callout type="info">
  Loops execute sequentially, not in parallel. If you need concurrent execution, use the Parallel block instead.
</Callout>

## Inputs and Outputs

<Tabs items={['Configuration', 'Variables', 'Results']}>
  <Tab>
    <ul className="list-disc space-y-2 pl-6">
      <li>
        <strong>Loop Type</strong>: Choose between 'for', 'forEach', 'while', or 'doWhile'
      </li>
      <li>
        <strong>Iterations</strong>: Number of times to execute (for loops)
      </li>
      <li>
        <strong>Collection</strong>: Array or object to iterate over (forEach loops)
      </li>
      <li>
        <strong>Condition</strong>: Boolean expression to evaluate (while/do-while loops)
      </li>
    </ul>
  </Tab>
  <Tab>
    Available **inside** the loop only:
    <ul className="list-disc space-y-2 pl-6">
      <li>
        <strong>{"<loop.index>"}</strong>: Current iteration number (0-based)
      </li>
      <li>
        <strong>{"<loop.currentItem>"}</strong>: Current item being processed (forEach only)
      </li>
      <li>
        <strong>{"<loop.items>"}</strong>: Full collection (forEach only)
      </li>
    </ul>
  </Tab>
  <Tab>
    <ul className="list-disc space-y-2 pl-6">
      <li>
        <strong>{"<blockname.results>"}</strong>: Array of all iteration results (accessed via block name)
      </li>
      <li>
        <strong>Structure</strong>: Results maintain iteration order
      </li>
      <li>
        <strong>Access</strong>: Available in blocks after the loop completes
      </li>
    </ul>
  </Tab>
</Tabs>

## Best Practices

- **Set reasonable limits**: Keep iteration counts reasonable to avoid long execution times
- **Use ForEach for collections**: When processing arrays or objects, use ForEach instead of For loops
- **Handle errors gracefully**: Consider adding error handling inside loops for robust workflows