Skip to main content
ForEach is a control-flow component that iterates over a list in your data, rendering its children once per item. Each iteration receives the list item as the interpolation context, so {{ field }} placeholders resolve to that item’s values.

​
Basic Usage

When rendered with the data above, this produces one card per crew member.

​
How It Works

The key argument (passed positionally or as a keyword) names the field in the data dict that contains the list. At render time, ForEach iterates that list. If each item is a dict, its keys become the interpolation context for that iteration. If an item is a scalar, it’s available as {{ $item }}. With {"tags": ["earth", "magrathea", "vogon poetry", "42"]}, this renders one badge per item.

​
Iteration Variables

Beyond the item’s own fields, every iteration exposes two special variables: $index (zero-based position) and $item (the entire current item). Individual fields like {{ name }} are still available directly — $item is for when you need to pass the whole object somewhere, like an action argument. $index is especially useful for actions that target a specific list position — SetState("items.{{ $index }}.done", true) updates the done field of the current item. And $item lets you pass the whole object to actions like ToolCall("edit_user", arguments={"user": "{{ $item }}"}).

​
Nested Data

Since each item becomes the full interpolation context for that iteration, you can access nested fields with dot notation:

​
API Reference

ForEach Parameters

​
key
str
required
The data field containing the list to iterate over. Can be passed as a positional argument.
​
css_class
str | None
default:"None"
Additional Tailwind CSS classes for the wrapper element.

​
Protocol Reference

ForEach
{
  "type": "ForEach",
  "children?": "[Component]",
  "key": "string (required)",
  "cssClass?": "string"
}
For the complete protocol schema, see ForEach.