> ## Documentation Index
> Fetch the complete documentation index at: https://helpdocs.gavel.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Repeating Items
> Use Gavel's Repeating Item question type to collect variable-length lists, nest repeating items, apply conditionals, and count entries in your documents.
Many legal documents require information about a variable number of people or things: a client's children, the parties to a contract, a list of assets in an estate, or the shareholders of a company. You never know in advance how many entries there will be — it could be one or twenty. **Repeating Items** (also called looping lists) are designed exactly for this. A Repeating Item question lets respondents add as many entries as they need, and Gavel loops through all of them to populate your document.
Repeating Item questions must be placed on their own dedicated page. Do not add other question types to the same page as a Repeating Item. Create a new page in the Builder before adding one.
***
## How repeating items work
When you add a Repeating Item question, you define:
* **The item name** — a variable name representing the collection (e.g., `children`, `assets`, `parties`)
* **The attributes** — sub-questions for each entry (e.g., `FirstName`, `dob`, `address`)
The respondent adds entries one at a time, answering the attribute questions for each. Gavel collects all entries and stores them as a list. Your document template then loops through that list to output each entry.
***
## Basic document syntax
Use this pattern in your Word document template to output data from a Repeating Item:
```text theme={null}
{% for item in ItemName %}
{{ item.ItemAttributeName }}
{% endfor %}
```
* `ItemName` — the variable name you gave the repeating item
* `ItemAttributeName` — the variable name of a specific attribute (sub-question)
**Example — children's names and birthdates:**
```text theme={null}
{% for item in children %}
Name: {{ item.FirstName }}
Birthdate: {{ item.dob }}
{% endfor %}
```
### Bulleted or numbered lists
To output repeating item data as a bulleted list, apply Word's list style to the attribute line inside the loop:
```text theme={null}
{% for item in ItemName %}
- {{ item.ItemAttributeName }}
{% endfor %}
```
### Tables
To populate a table in your Word document with repeating item data, add the for/endfor tags to the first and last rows of the table respectively, with attribute variables in the middle rows. Gavel will generate a new table row for each entry in the list.
***
## Reference a repeating item question
Refer to the responses to a prior Repeating Item question in a subsequent question using the two steps below.
### Step 1. Add a "repeating item reference" question to the workflow
1. Once you have created a repeating item question, create a choice question or a Repeating Item with a choice attribute. (Choice questions can be single-select, multi-select, combobox, or dropdown.)
2. Select the **Reference a repeating item** checkbox.
3. Select the repeating item you're referencing and up to two attributes to display.
All the data from the repeating item comes with that selection. If you have a repeating item "children," and a single select question referencing "children," it will pull all the information about that child you gathered in the repeating item. No need to regather that information!
### Step 2. Add variables to the document
Because each repeating item may have multiple attributes (e.g., children could have attributes such as first name, last name, date of birth, residence, etc.), you need to reference the appropriate attribute, which varies depending on the question type.
#### Option 1: Single-select or dropdown question referencing a repeat
```text theme={null}
{{ VariableName.ItemAttribute }}
```
**Example:**
```text theme={null}
{{ favorite_child.child_first_name }} {{ favorite_child.child_last_name }}
```
#### Option 2: Multi-select question referencing a repeat
```text theme={null}
{% for item in MultiSelectVariableName %}{{ item.ItemAttribute }}{% endfor %}
```
**Example:**
```text theme={null}
{% for item in favorite_child %}{{ item.child_first_name }} {{ item.child_last_name }}{% endfor %}
```
To make it a comma list, use the regular commalist formatting:
```text theme={null}
{{ commalist(VariableName, '') }}
```
To count how many items were selected in the multi-select:
```text theme={null}
{% if (MultiSelectVariableName.true_values())|length > 1 %}TEXT HERE.{% endif %}
```
#### Option 3: Repeating Item question referencing a repeat
```text theme={null}
{% for item in SecondItem %} {{ item.ItemAttribute.FirstItemAttribute }} {% endfor %}
```
**Example** — if the second item is `grandchildren` and we're asking who each grandchild belongs to:
```text theme={null}
{% for item in grandchildren %}
{{ item.grandchildname }} is the child of {{ item.grandchildparent.child_first_name }}
{% endfor %}
```
**Example where the attribute is a multi-select:** If the repeating item referencing the first repeating item is a multi-select, the syntax will be slightly different, since a multi-select is a list of items, too.
Use this syntax for a comma list:
```text theme={null}
{% for item in Item2Name %}{{ commalist(item.Item2Attribute,"") }}{% endfor %}
{% for item in grandchildren %}{{ commalist(item.grandchildparent,"") }}{% endfor %}
```
Use this syntax for a multi-line list:
```text theme={null}
{% for item in Item2Name %}{% for selection in item.Item2Attribute %}{{ selection.Item1Attribute }}
{% endfor %}{% endfor %}
{% for item in grandchildren %}{% for selection in item.grandchildparent %}{{ selection.child_first_name }}
{% endfor %}{% endfor %}
```
***
## Reference a repeating item question
Refer to the responses to a prior Repeating Item question in a subsequent question using the two steps below.
### Step 1. Add a "repeating item reference" question to the workflow
1. Once you have created a repeating item question, create a choice question or a Repeating Item with a choice attribute. (Choice questions can be single-select, multi-select, combobox, or dropdown.)
2. Select the **Reference a repeating item** checkbox.
3. Select the repeating item you're referencing and up to two attributes to display.
All the data from the repeating item comes with that selection. If you have a repeating item "children," and a single select question referencing "children," it will pull all the information about that child you gathered in the repeating item. No need to regather that information!
### Step 2. Add variables to the document
Because each repeating item may have multiple attributes (e.g., children could have attributes such as first name, last name, date of birth, residence, etc.), you need to reference the appropriate attribute, which varies depending on the question type.
#### Option 1: Single-select or dropdown question referencing a repeat
```text theme={null}
{{ VariableName.ItemAttribute }}
```
**Example:**
```text theme={null}
{{ favorite_child.child_first_name }} {{ favorite_child.child_last_name }}
```
#### Option 2: Multi-select question referencing a repeat
```text theme={null}
{% for item in MultiSelectVariableName %}{{ item.ItemAttribute }}{% endfor %}
```
**Example:**
```text theme={null}
{% for item in favorite_child %}{{ item.child_first_name }} {{ item.child_last_name }}{% endfor %}
```
To make it a comma list, use the regular commalist formatting:
```text theme={null}
{{ commalist(VariableName, '') }}
```
To count how many items were selected in the multi-select:
```text theme={null}
{% if (MultiSelectVariableName.true_values())|length > 1 %}TEXT HERE.{% endif %}
```
#### Option 3: Repeating Item question referencing a repeat
```text theme={null}
{% for item in SecondItem %} {{ item.ItemAttribute.FirstItemAttribute }} {% endfor %}
```
**Example** — if the second item is `grandchildren` and we're asking who each grandchild belongs to:
```text theme={null}
{% for item in grandchildren %}
{{ item.grandchildname }} is the child of {{ item.grandchildparent.child_first_name }}
{% endfor %}
```
**Example where the attribute is a multi-select:** If the repeating item referencing the first repeating item is a multi-select, the syntax will be slightly different, since a multi-select is a list of items, too.
Use this syntax for a comma list:
```text theme={null}
{% for item in Item2Name %}{{ commalist(item.Item2Attribute,"") }}{% endfor %}
{% for item in grandchildren %}{{ commalist(item.grandchildparent,"") }}{% endfor %}
```
Use this syntax for a multi-line list:
```text theme={null}
{% for item in Item2Name %}{% for selection in item.Item2Attribute %}{{ selection.Item1Attribute }}
{% endfor %}{% endfor %}
{% for item in grandchildren %}{% for selection in item.grandchildparent %}{{ selection.child_first_name }}
{% endfor %}{% endfor %}
```
***
## Nested repeating items
You can add a Repeating Item **inside** another Repeating Item to collect data about sub-lists that belong to each entry in the parent list. For example: a list of children (parent repeating item), where each child may have their own list of grandchildren (nested repeating item).
### Setting up nested repeating items
1. Add a Repeating Item question for the parent list (e.g., `children`). It must be on its own page.
2. Add at least one attribute question to the parent Repeating Item.
3. Click **Add another** within the Repeating Item editor and choose **Repeating Item** as the question type.
4. Give the nested item a name (e.g., `grandchildren`) and add its attribute questions.
You can optionally ask an **initial question** (such as "Does this child have any children?") before the nested entries are collected. This is recommended when the nested list may be empty for some parent entries.
### Page titles for nested items
Because nested Repeating Items always display on their own page during the questionnaire, you can customize the page title to show context from the parent entry. Use the syntax:
```text theme={null}
${ ItemName[i].AttributeName }
```
**Example** — show the child's name when asking about their grandchildren:
```text theme={null}
${ children[i].ChildName }
```
### Nested repeating items in Word documents
```text theme={null}
{% for item in ItemName %}
{% for nesteditem in item.NestedItemName %}
{{ nesteditem.NestedAttributeName }}
{% endfor %}{% endfor %}
```
**Example:**
```text theme={null}
{% for item in children %}
My child {{ item.ChildName }} has the following children:
{% for nesteditem in item.grandchildren %}
Name: {{ nesteditem.FirstName }}
Birthdate: {{ nesteditem.dob }}
{% endfor %}{% endfor %}
```
### Nested repeating items in PDFs
To reference a specific entry from a nested repeating item in a PDF field, use:
```text theme={null}
${ ItemName[#].NestedItemName[##].AttributeName if len(ItemName)># and len(ItemName[#].NestedItemName)>## else "" }
```
* `#` — zero-based index of the parent entry (0 = first, 1 = second, etc.)
* `##` — zero-based index of the nested entry
**Example** — first child's third grandchild's name:
```text theme={null}
${ children[0].grandchildren[2].grandchildname if len(children)>0 and len(children[0].grandchildren)>2 else "" }
```
***
## Conditionals with repeating items
You can write conditional text in your documents based on the number of repeating item entries or on the value of a specific attribute.
### Conditional text based on count
```text theme={null}
{% if ItemName.number() == 0 %}There are no entries.{% endif %}
{% if ItemName.number() > 1 %}There is more than one entry.{% endif %}
```
**Example:**
```text theme={null}
{% if children.number() == 1 %}There is one child.{% else %}There is more than one child or no children.{% endif %}
```
### Conditional text within a loop
```text theme={null}
{% for item in ItemName %}
{{ item.AttributeName }}{% if item.Attribute == "Value" %} Some conditional text.{% endif %}
{% endfor %}
```
**Example** — add a note when a child's gender is female:
```text theme={null}
{% for item in Children %}
The child's name is {{ item.childname }}. {% if item.childgender == "Female" %}She's a female.{% endif %}
{% endfor %}
```
### Filter the loop to only matching items
To output only entries where a specific attribute matches a value:
```text theme={null}
{% for item in ItemName if item.ItemAttribute == "Value" %}
{{ item.AnotherAttribute }}
{% endfor %}
```
**Example** — list only female children:
```text theme={null}
{% for item in Children if item.Gender == "Female" %}{{ item.FullName }}, {% endfor %}
```
### Test whether multiple entries share an attribute
```text theme={null}
{% if ItemName|selectattr("Attribute", "equalto", "Value")|list|length > 1 %}
Conditional text.
{% endif %}
```
**Example** — check if two or more children are female:
```text theme={null}
{% if children|selectattr("childgender", "equalto", "Female")|list|length >= 2 %}
Two or more kids are female.
{% endif %}
```
***
## Counting and referencing specific entries
### Display the total count
```text theme={null}
{{ ItemName.number() }}
```
### Reference a specific entry by position
```text theme={null}
{{ ItemName[0].ItemAttribute }}
```
Remember: the list is zero-indexed. The first entry is `[0]`, the second is `[1]`, and so on.
**Example** — first and third child's name:
```text theme={null}
{{ children[0].firstname }} and {{ children[2].firstname }}
```
### Reference the entry's position within the loop
```text theme={null}
{% for item in children %}{{ item.childname }} is my child number {{ loop.index }}{% endfor %}
```
Output: "Jane is my child number 1. Jill is my child number 2."
### Calculate the sum of a numeric attribute
```text theme={null}
{{ repeating_item_sum(ItemName, "item.ItemAttribute") }}
```
**As currency:**
```text theme={null}
{{ currency(repeating_item_sum(ItemName, "item.ItemAttribute")) }}
```
**Example** — sum the cost of all assets:
```text theme={null}
{{ repeating_item_sum(assets, "item.cost") }}
```
### Advanced position-based text
Add text only when an item is **not** the last in the list:
```text theme={null}
{% if not loop.last %}something{% endif %}
```
Add the word "and" before the second-to-last item:
```text theme={null}
{% if loop.revindex == 2 %} and{% endif %}
```
***
## Tips for working with repeating items
Repeating Item questions cannot share a page with other question types. Create a dedicated page before adding the question.
Use short, lowercase variable names for repeating items (e.g., `children`, `assets`, `parties`). These appear repeatedly in your document syntax.
When there might be zero entries (e.g., "Does this client have children?"), enable the initial question to avoid empty loops in your document.
Always test your repeating item workflow by adding two or three entries. A single entry can mask looping issues that appear with multiple entries.