Skip to main content
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: 
{% 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: 
{% 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: 
{% 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

{{ VariableName.ItemAttribute }}
Example: 
{{ favorite_child.child_first_name }} {{ favorite_child.child_last_name }}

​
Option 2: Multi-select question referencing a repeat

{% for item in MultiSelectVariableName %}{{ item.ItemAttribute }}{% endfor %}
Example: 
{% 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: 
{{ commalist(VariableName, '<ItemAttribute>') }}
To count how many items were selected in the multi-select: 
{% if (MultiSelectVariableName.true_values())|length > 1 %}TEXT HERE.{% endif %}

​
Option 3: Repeating Item question referencing a repeat

{% for item in SecondItem %} {{ item.ItemAttribute.FirstItemAttribute }} {% endfor %}
Example — if the second item is grandchildren and we’re asking who each grandchild belongs to: 
{% 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: 
{% for item in Item2Name %}{{ commalist(item.Item2Attribute,"<Item1Attribute>") }}{% endfor %}
{% for item in grandchildren %}{{ commalist(item.grandchildparent,"<child_first_name>") }}{% endfor %}
Use this syntax for a multi-line list: 
{% 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

{{ VariableName.ItemAttribute }}
Example: 
{{ favorite_child.child_first_name }} {{ favorite_child.child_last_name }}

​
Option 2: Multi-select question referencing a repeat

{% for item in MultiSelectVariableName %}{{ item.ItemAttribute }}{% endfor %}
Example: 
{% 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: 
{{ commalist(VariableName, '<ItemAttribute>') }}
To count how many items were selected in the multi-select: 
{% if (MultiSelectVariableName.true_values())|length > 1 %}TEXT HERE.{% endif %}

​
Option 3: Repeating Item question referencing a repeat

{% for item in SecondItem %} {{ item.ItemAttribute.FirstItemAttribute }} {% endfor %}
Example — if the second item is grandchildren and we’re asking who each grandchild belongs to: 
{% 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: 
{% for item in Item2Name %}{{ commalist(item.Item2Attribute,"<Item1Attribute>") }}{% endfor %}
{% for item in grandchildren %}{{ commalist(item.grandchildparent,"<child_first_name>") }}{% endfor %}
Use this syntax for a multi-line list: 
{% 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: 
${ ItemName[i].AttributeName }
Example — show the child’s name when asking about their grandchildren: 
${ children[i].ChildName }

​
Nested repeating items in Word documents

{% for item in ItemName %}
{% for nesteditem in item.NestedItemName %}
{{ nesteditem.NestedAttributeName }}
{% endfor %}{% endfor %}
Example: 
{% 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: 
${ 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: 
${ 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

{% if ItemName.number() == 0 %}There are no entries.{% endif %}
{% if ItemName.number() > 1 %}There is more than one entry.{% endif %}
Example: 
{% if children.number() == 1 %}There is one child.{% else %}There is more than one child or no children.{% endif %}

​
Conditional text within a loop

{% 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: 
{% 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: 
{% for item in ItemName if item.ItemAttribute == "Value" %}
{{ item.AnotherAttribute }}
{% endfor %}
Example — list only female children: 
{% for item in Children if item.Gender == "Female" %}{{ item.FullName }}, {% endfor %}

​
Test whether multiple entries share an attribute

{% if ItemName|selectattr("Attribute", "equalto", "Value")|list|length > 1 %}
Conditional text.
{% endif %}
Example — check if two or more children are female: 
{% 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

{{ ItemName.number() }}

​
Reference a specific entry by position

{{ 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: 
{{ children[0].firstname }} and {{ children[2].firstname }}

​
Reference the entry’s position within the loop

{% 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

{{ repeating_item_sum(ItemName, "item.ItemAttribute") }}
As currency: 
{{ currency(repeating_item_sum(ItemName, "item.ItemAttribute")) }}
Example — sum the cost of all assets: 
{{ repeating_item_sum(assets, "item.cost") }}

​
Advanced position-based text

Add text only when an item is not the last in the list: 
{% if not loop.last %}something{% endif %}
Add the word “and” before the second-to-last item: 
{% if loop.revindex == 2 %} and{% endif %}

​
Tips for working with repeating items

Always use a separate page

Repeating Item questions cannot share a page with other question types. Create a dedicated page before adding the question.

Keep item names simple

Use short, lowercase variable names for repeating items (e.g., children, assets, parties). These appear repeatedly in your document syntax.

Use the initial question option

When there might be zero entries (e.g., “Does this client have children?”), enable the initial question to avoid empty loops in your document.

Test with multiple entries

Always test your repeating item workflow by adding two or three entries. A single entry can mask looping issues that appear with multiple entries.