> For the complete documentation index, see [llms.txt](https://developer.collibra.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.collibra.com/workflows/designing-workflows/forms/form-components/subform.md).

# Subform

The **Subform** component adds an entire, pre-defined form template as a section in your main form. Use this component to achieve reusability of common form sections, manage complex forms by breaking them down into modular and manageable parts, or create repeating sections, such as one to allow users to add multiple contacts, each with the same set of fields. It inherently includes all components and logic defined in the embedded subform template.

Use the **Form reference** attribute to include an existing form in the subform component. You can use the subform as a collection of components. You can also bind it to another component by selecting the **Store subform data in single variable** attribute and providing the variable that stores the values from the linked component.

{% hint style="info" %}
[Outcome buttons](/workflows/designing-workflows/forms/form-outcomes.md) are not available in subforms.
{% endhint %}

## General properties

| Property                                                                                                                                                                                                                                                                                                                                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ID                                                                                                                                                                                                                                                                                                                                                                                 | The identifier of the component, primarily used for client-side interactions and identification in the HTML structure of the form. When you add a component, an ID is automatically generated to ensure it is unique in the form.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Label                                                                                                                                                                                                                                                                                                                                                                              | Text that appears above the form component in Collibra, briefly describing its purpose. This is the main title or question for the field.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Label tooltip                                                                                                                                                                                                                                                                                                                                                                      | <p>Additional help or information about the field. If defined, a question mark icon appears after the label, showing the tooltip when users hover their pointer over the icon.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The tooltip supports plain text only.</p></div>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Documentation                                                                                                                                                                                                                                                                                                                                                                      | A text field for internal design notes or future reference about this specific component. This information is not visible in Collibra.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Store subform data in single variable                                                                                                                                                                                                                                                                                                                                              | <p>This property controls how data from the fields in a subform is stored and whether users can add multiple instances of the subform at runtime.</p><ul><li>Not set: The values from the fields inside the subform are stored directly as individual variables in the <a href="/pages/EA2FIoQwHII4yTGI6hcr">scope</a> of the parent form. For example, if a field in the subform is bound to a variable called <code>{{projectName}}</code>, its value is stored in the <code>projectName</code> variable in the parent form. In this mode, users can add only a single instance of the subform.</li><li><p>Set: All data from the fields inside the subform are collected and stored as a single LinkedHashMap variable as String. You must provide a variable name for the subform component. For example, if the subform variable is <code>{{mySubformData}}</code> and the subform contains fields that store data in <code>{{firstName}}</code> and <code>{{lastName}}</code> , the submitted data is stored as <code>mySubformData.firstName</code> and <code>mySubformData.lastName</code> in the single <code>mySubformData</code> variable:</p><pre><code>"mySubformData": { |
| "firstName": "...",                                                                                                                                                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| "lastName": "..."                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| }                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| </code></pre><p>To access data outside of the form scope, use the following keywords to specify the outer scope:</p><p>$itemParentProvides read-only access to the parent scope data, for example <code>{{$itemParent.variableName}}</code>.$payloadProvides read and write access to the full workflow payload, for example <code>{{$payload.variableName}}</code>.</p></li></ul> |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Form reference                                                                                                                                                                                                                                                                                                                                                                     | A reference to the form to be used as a subform.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

## Form properties

<table><thead><tr><th>Property</th><th>Description</th></tr></thead><tbody><tr><td>Show border</td><td>Whether the subform has a visual border around it in Collibra.</td></tr><tr><td>Collapsible</td><td><p>Whether users can collapse or expand the component in Collibra.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Enabling this option adds a + / - icon in the upper-right corner of the subform, allowing users to toggle its visibility.</p></div></td></tr><tr><td>Initially collapsed</td><td>Whether the component is shown in a collapsed state when the form initially loads in Collibra.</td></tr><tr><td>Multiple elements</td><td><p>Whether users can add multiple instances of the subform fields. This property is available when the subform is configured to <strong>Store subform data in single variable</strong>.</p><p>When multiple instances are created, the subform variable becomes a list of maps. Each object in the list represents one subform instance:</p><pre><code>"mySubformData": [
  {
    "firstName": "...",
    "lastName": "..."
  },
  {
    "firstName": "...",
    "lastName": "..."
  }
]
</code></pre><p>You can use the <code>$index</code> keyword to retrieve the position number of each subform instance in the list, starting from zero. For example, use the expression <code>{{$index == 0}}</code> in the <strong>Visible</strong> property of a subform component to show that component only in the first instance.</p></td></tr><tr><td>Show add button</td><td>Shows and <strong>Add</strong> button in the subform to add new instances of subform items. This property is only applicable when <strong>Store subform data in single variable</strong> and <strong>Multiple elements</strong> are enabled.</td></tr><tr><td>Add button text</td><td>A custom label for the button that adds subform items. This property is only applicable when <strong>Show add button</strong> is enabled.</td></tr><tr><td>Show remove button</td><td>Shows a trash can icon to delete individual instances of subform items. This property is only applicable when <strong>Multiple elements</strong> is enabled.</td></tr><tr><td>Instance unique key (expression)</td><td>Currently not in use.</td></tr><tr><td>Show no items message</td><td>Shows the message <em>No items yet, please click ADD to create one</em> in the subform area when it is empty. This property is only applicable when <strong>Multiple elements</strong> is enabled.</td></tr><tr><td>No items message</td><td>A custom message to show when the subform is empty. This property is only applicable when <strong>Show no items message</strong> is enabled.</td></tr></tbody></table>

## Validation properties

| Attribute          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Minimum elements   | The minimum number of items to be selected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Maximum elements   | The maximum number of items that can be selected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Custom validations | <p>A list of additional validations for the component. Each custom validation consists of two parts:</p><ul><li><strong>Expression</strong>: A rule that must evaluate to <code>true</code> for the form to be submitted.</li><li><strong>Error message</strong>: The message that shows if the expression evaluates to <code>false</code>.</li></ul><p>For example, you can create a validation with the expression <code>{{experience>2}}</code>. This expression evaluates to <code>true</code> only if the value of the <code>experience</code> variable is greater than 2.</p> |

### Validation messages

| Attribute        | Description                                                                                                          |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- |
| Minimum elements | The error message that shows if the number of selected items is less than the required minimum number of elements.   |
| Maximum elements | The error message that shows if the number of selected items is greater than the allowed maximum number of elements. |

## Rendering properties

| Property | Description                                                                                                                                                                                                                                                                           |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ignored  | Whether the component is be hidden in the form and any value it might hold is not included in the submission data.                                                                                                                                                                    |
| Visible  | Whether the component is shown or hidden on the form. You can controlled this unconditionally or through an expression. For example, you can set an expression that hides or shows the component based on a user selection in another component. This property is enabled by default. |
| Enabled  | Whether the component is interactive or read-only on the form. When disabled, users cannot change the component value. This property is enabled by default.                                                                                                                           |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.collibra.com/workflows/designing-workflows/forms/form-components/subform.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.