> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Collection Prototype

> Create dynamic, data-driven interfaces with different layouts based on item properties using collection prototypes.

> [!NOTE]
>
> Collection prototypes allow you to display items within a collection using different layouts based on their properties, creating more dynamic and context-aware user interfaces.

## What are collection prototypes?

Collection prototypes are specialized components that define different display formats for items within a single collection. They act as templates that are applied conditionally based on item properties, allowing you to:

* Display collection items with different layouts based on their data properties
* Create visually distinct displays for featured or highlighted items
* Apply specialized formatting for different item types or states
* Integrate custom components for enhanced functionality
* Add interactive features like item selection

> [!NOTE]
>
> Collection prototypes always work as child components within a parent [Collection component](../collection). While a Collection iterates through a data array, Collection Prototypes determine how each individual item should be displayed.

## How collection prototypes work

### Core concepts

Collection prototypes use a simple mechanism to determine which layout to apply to each item. The behavior depends on whether you have one or multiple prototypes:

> [card] Prototype identifier key (PIK)
>
> The data property used to determine which prototype to apply (e.g., `type`, `status`, `priority`)

> [card] Prototype identifier value (PIV)
>
> The specific value that triggers this prototype layout (e.g., `featured`, `active`, `high`)

### Selection mode

Each prototype has a **Selection mode** in its **General** settings:

* **Key–value**: the prototype matches an item when the item's **Prototype identifier key** (PIK) holds the **Prototype identifier value** (PIV).
* **Expression**: the prototype matches an item when its **Selection condition** is true. The condition reads the fields of the collection item, for example `${type} === 'featured' && ${price} > 100`.

New prototypes start in **Expression** mode. Prototypes that existed before FlowX.AI 6.0.0 keep **Key–value**.

### When to configure PIK and PIV

> [tab] Single prototype
>
> **Configuration**: PIK and PIV are **optional** and should **not** be configured
>
> > [!NOTE]
> >
> > If you have only one collection prototype, the system will automatically use that prototype for all items in the array, regardless of their properties. In this case, leave both PIK and PIV empty.

> [tab] Multiple prototypes
>
> **Configuration**: In **Key–value** mode, PIK and PIV are **required** and **both must be completed**. In **Expression** mode, set a **Selection condition** instead.
>
> > [!WARNING]
> >
> > When using multiple collection prototypes, give each prototype a way to match: both PIK and PIV in **Key–value** mode, or a **Selection condition** in **Expression** mode. A key-value prototype with only one of the two fields set is reported as an error in the Issues Console.
>
> When the collection renders, each item is evaluated against the prototypes in order, and the first prototype that matches renders the item. A prototype with no PIK and PIV, or no selection condition, is never matched: it is the fallback for items that match no other prototype. If there is no fallback prototype, the item uses the first prototype in the collection. Only one fallback prototype is used, and the Issues Console reports any others.

### Visual examples

> [tab] Single prototype scenario
>
> **Use case**: Displaying a list of menu items where all items have the same layout
>
> ```javascript theme={"dark"}
> // Data structure - all items use the same prototype
> [
>   {
>     "name": "Margherita Pizza",
>     "price": 12.99,
>     "description": "Classic tomato and mozzarella"
>   },
>   {
>     "name": "Caesar Salad", 
>     "price": 8.99,
>     "description": "Fresh romaine with parmesan and croutons"
>   }
> ]
> ```
>
> **Configuration**:
>
> * PIK: *(leave empty)*
>
> * PIV: *(leave empty)*
>
> > [!NOTE]
> >
> > Since all items use the same layout, no prototype identification is needed.

> [tab] Multiple prototypes scenario
>
> **Use case**: Restaurant menu with different layouts for main courses vs desserts
>
> ```javascript theme={"dark"}
> // Data structure with type field for prototype identification
> [
>   {
>     "name": "pizza",
>     "type": "main course",
>     "price": 15.99,
>     "ingredients": ["tomato", "mozzarella", "basil"]
>   },
>   {
>     "name": "cremsnit",
>     "type": "dessert", 
>     "price": 6.99,
>     "sweetness": "medium"
>   }
> ]
> ```
>
> **Configuration for main course prototype**:
>
> * PIK: `type`
> * PIV: `main course`
>
> **Configuration for dessert prototype**:
>
> * PIK: `type`
>
> * PIV: `dessert`
>
> > [!TIP]
> >
> > Each item's `type` property determines which prototype layout to use.

![Acme Bank products collection rendered at runtime, four product cards with Product Two Premium selected](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/collection-render-prototypes.png)

Collection with multiple prototypes in action

> [accordion] Normal product display
>
> ![Normal product prototype with Prototype identifier key type and Prototype identifier value normal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/collection-prototype-normal.png)

> [accordion] Recommended product display
>
> ![Recommended product prototype with Prototype identifier key type and Prototype identifier value recommended](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/collection-prototype-recommended.png)

## Implementation guide

### 1. Prepare your data

Before implementing collection prototypes, you need to prepare the data structure that will determine which prototype applies to each item.

#### Using a service task node

The most common approach is to use a Service Task node with business rules:

**1. Add a Service Task Node**

In the FlowX.AI Designer, add a **Service Task** node before your User Task node and connect them with a sequence flow.

![Adding a Service Task node to your process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/task_node_array.png)

Adding a Service Task node

**2. Configure the Business Rule**

Select your Service Task node, open the **Actions** tab, and add an action with the **Business Rule** action type, or edit an existing one.

![Configuring a business rule in a Service Task node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/6.x-collection-prototype-prepare-array.png)

Configuring a business rule

**3. Write the Data Preparation Code**

Use JavaScript to create your data structure and assign it to the process context:

```javascript theme={"dark"}
// Create the data structure for products
const products = [
{
  "name": "Product One Plus",
  "description": "The plus option",
  "type": "normal",  // This property will determine which prototype to use
  "price": 99.99
},
{
  "name": "Product Two Premium",
  "description": "This is premium product",
  "type": "recommended",  // This will use a different prototype
  "price": 149.99
},
{
  "name": "Product Basic",
  "description": "The most basic option",
  "type": "normal",
  "price": 49.99
}
];

// Add the products array to the process data
output.put("products", products);
```

**4. Test Your Data**

Save your configuration, and test your business rule by using the **Test Rule** feature in the business rules editor to make sure the data is correctly added to the process context.

![Verifying business rule output](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/test_your_data.png)

Verifying business rule output

### 2. Create the UI components

Once your data is prepared, you can implement the collection and its prototypes in the UI Designer:

**1. Create a User Task Node**

In the FlowX.AI Designer, create or select an existing **User Task** node in your process and click the **brush icon** to open the UI Designer.

![Opening the UI Designer from a User Task node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/add_user_task_node_for_collection.gif)

Opening the UI Designer for a User Task node

**2. Add a Collection Component**

Add a **root component** (like a Card or Container) to your node, then add a **Collection** component inside it. Configure the Collection's **source** to point to your data array (e.g., `products`).

![Adding a Collection component in the UI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/collection_prototype_source.png)

Adding a Collection component

> [!NOTE]
>
> The `collectionSource` property specifies the process key where your list can be found. It should be a valid array of objects. For example, if your data is at `processData.products`, you would set the source to `products`.

**3. Add Collection Prototypes**

> [tab] Single prototype (simple case)
>
> For a single prototype that applies to all items:
>
> 1. Click on your Collection component to select it
>
> 2. Add a **Collection Prototype** as a child component
>
> 3. **Leave PIK and PIV empty** - no configuration needed
>
> 4. The prototype will automatically apply to all items in the collection
>
> > [!NOTE]
> >
> > This is the most common scenario when all items in your collection should have the same layout.

> [tab] Multiple prototypes (advanced case)
>
> For different display types based on item properties:
>
> 1. Click on your Collection component to select it
> 2. Add a **Collection Prototype** as a child component
> 3. Configure the prototype's settings:
>    * **Prototype identifier key**: The field to check (e.g., `type`)
>    * **Prototype identifier value**: The value to match (e.g., `normal`)
>
> ![Collection with two Collection Prototypes in the component tree and the Key-value selection mode settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/collection-prototype-tree.png)
>
> Configuring a Collection Prototype
>
> 4. Repeat for each different prototype you need, using different identifier values
>
> > [!WARNING]
> >
> > In **Key–value** mode, set both PIK and PIV on each prototype that should match specific items. Leave both empty only on the one fallback prototype. In **Expression** mode, set a **Selection condition** instead.

**4. Design Each Prototype's Layout**

For each prototype, add the UI components that will display your data:

1. Select a Collection Prototype
2. Add components like **Text**, **Image**, **Button**, etc.
3. Configure each component to use relative paths to the collection item data saved in the Data Model:
   * Use text UI element with the key `${name}`
   * Use text UI element with the key `${description}`

![Adding a Basic component to a Collection Prototype from the add child menu](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/collection-prototype-add-component.png)

Adding components to a prototype

> [!NOTE]
>
> Components within a collection use **relative paths** to the collection source. This means that wherever the collection is found inside the process data, the components inside the collection need their keys configured relative to that collection.
>
> ![Text component inside a Collection Prototype bound to the relative key description](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/collection-relative-key.png)

### 3. Add interactivity

To make your collection items interactive, such as allowing users to select an item:

**1. Create a Node Action**

Add an [Action](https://docs.flowx.ai/6.x/docs/building-blocks/actions/actions.md) to your [User task node](https://docs.flowx.ai/6.x/docs/building-blocks/node/user-task-node.md):

1. Go back to the process designer
2. Select your User Task node
3. Go to the **Actions** tab
4. Add a new action with:
   * Action type: **Save Data**
   * Name: (e.g., `selectItem`)

![Configuration screen for node action setup](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/6.x-collection-prototype-add-interactivity.png)

Adding a Node Action

**Configuration options:**

* Under **Trigger**, turn on **Manual**, since users trigger it
* Under **Execution**, leave **Optional** off if a selection is required to proceed
* Turn on **Repeatable** for changeable selections

**2. Configure an event handler**

Add an event handler to your collection prototype:

1. Return to the UI Designer
2. Select the component in your prototype that should trigger the action
3. In the Settings panel, add an event handler
4. Add a  **Collection item save key**.
5. Under **Add custom keys**, add a key that matches the **Collection item save key**.

![Add new event handler dialog on a Collection Prototype with Collection item save key selectedProduct and a custom key](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/collection-item-save-key.png)

Adding an event handler

**3. Test the Interaction**

Save your changes and test your process to verify that:

* Different items display with the correct prototype layouts
* Interactive elements work as expected
* Selected data is properly saved to your process data

> [accordion] Before selection
>
> ![Process data state before item selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/collection-prototype-variables-before.png)

> [accordion] After selection
>
> ![Process data state after item selection showing selected product data](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/collection-prototype-variables-after.png)

## Best practices

### Working with custom components

> [!TIP]
>
> When integrating custom components into collection prototypes, follow these best practices:

1. **Use relative paths for data access**
   * Configure input keys relative to collection items
   * Example: Use `name` instead of `app.clients.name`

2. **Maintain consistent data structures**
   * Ensure required data exists in collection items
   * Follow consistent data patterns across all items

### Data access patterns

> [tab] Outside collections
>
> Components use full paths from data root:
>
> ```jsx theme={"dark"}
> // Input keys:
> // app.name
> // app.signatureImageURL
>
> data: {
>     app: {
>         name: "John Doe",
>         signatureImageURL: "http://example.com/signature1.png"
>     }
> }
> ```

> [tab] Inside collections
>
> Components use relative paths:
>
> ```jsx theme={"dark"}
> // Input keys:
> // name
> // signatureImageURL
>
> data: {
>     name: "John Doe",
>     signatureImageURL: "http://example.com/signature1.png"
> }
> ```

### Performance optimization

* Limit the number of items in your collection when possible
* Simplify complex prototype layouts
* Consider pagination for large data sets
* Optimize images and other media within prototypes
* Avoid deeply nested components within prototypes

> [!TIP]
>
> **Pro tips:**
>
> * Test your collection prototypes with various data scenarios
> * Verify data flow through the entire selection process
> * Monitor the process data for correct updates
> * Ensure your UI provides clear visual feedback when an item is selected

## Troubleshooting

When working with collection prototypes, you might encounter some common issues:

### Common issues and solutions

> [accordion] Prototype not displaying correctly
>
> **Symptoms:**
>
> * Collection items appear with incorrect layouts
> * All items use the same prototype regardless of identifier values
> * Some items don't render at all
>
> **Solutions:**
>
> **For single prototype scenarios:**
>
> * Ensure PIK and PIV fields are **left empty** - they should not be configured
> * If you accidentally configured PIK/PIV for a single prototype, clear both fields
>
> **For multiple prototype scenarios:**
>
> * Verify that your **Prototype identifier key** exactly matches the property name in your data
>
> * Ensure the **Prototype identifier value** matches the expected values in your data
>
> * In **Key–value** mode, set both PIK and PIV: a prototype with only one of them is reported as an error in the Issues Console
>
> * Check for case sensitivity issues in both keys and values
>
> * Confirm that the parent Collection component has the correct source path
>
> > [!WARNING]
> >
> > With multiple prototypes, each prototype needs both PIK and PIV (Key–value mode) or a **Selection condition** (Expression mode). The exception is the one fallback prototype, which has neither and renders items that match no other prototype.

> [accordion] Event handlers not working
>
> **Symptoms:**
>
> * Clicking on items doesn't trigger the expected action
> * Selected data isn't saved to the process
> * No visual feedback when items are selected
>
> **Solutions:**
>
> * Confirm that the **Collection item save key** matches the key you added under **Add custom keys** in the event handler&#x20;
> * Verify that your node action is properly configured as **Manual** and **Repeatable** if needed
> * Check that the event handler is attached to the correct element within the prototype
> * Ensure the node action has the correct permissions and is properly linked

> [accordion] Data binding issues
>
> **Symptoms:**
>
> * Components inside prototypes show empty or incorrect data
> * Dynamic content doesn't update properly
> * Error messages in the console related to undefined properties
>
> **Solutions:**
>
> * Remember that components inside collections must use relative paths (e.g., `name` instead of `app.clients.name`)
> * Verify your data structure matches what the components expect
> * Check for null or undefined values that might cause rendering issues
> * Ensure your data is properly structured as an array of objects

### Known limitations

> [!WARNING]
>
> * **Deep data structures** might require careful handling of relative paths for proper data binding

### Debugging tips

1. **Use process data inspection:**
   * Monitor the process data before and after interactions with collection prototypes
   * Verify that selected items are correctly saved to the expected process data keys

2. **Test with simplified data:**
   * Start with a minimal data set to confirm basic functionality
   * Gradually add complexity to identify where issues might occur

3. **Isolate components:**
   * Test individual UI components outside the collection context
   * Add components to prototypes one by one to identify problematic elements

## Frequently asked questions

> [accordion] Can I use different layouts for mobile and desktop?
>
> Yes, you can create platform-specific overrides for your collection prototypes. Configure different layouts, spacing, and styling for Web, iOS, and Android platforms through the platform tabs in the UI Designer.

> [accordion] How do I handle missing identifier values?
>
> Items that don't match any prototype still render. To control their layout, add a fallback prototype: one with no PIK and PIV, or no **Selection condition**. A fallback prototype is never matched directly and renders any item no other prototype matches, wherever it sits in the component tree. Without a fallback prototype, unmatched items use the first prototype in the collection.

> [accordion] When should I configure PIK and PIV vs leaving them empty?
>
> **Leave PIK and PIV empty** when:
>
> * You have only one collection prototype
> * All items in your collection should use the same layout
>
> **Configure both PIK and PIV** when:
>
> * You have multiple collection prototypes
> * Different items should display with different layouts based on their properties
> * Both fields must be completed for the configuration to work

> [accordion] Can I use expressions in prototype identifier values?
>
> In **Key–value** mode, no: the prototype identifier value must be a static string that exactly matches the value in your data. To select prototypes with an expression, set the prototype's **Selection mode** to **Expression** and write a **Selection condition**, for example `${status} === 'overdue' || ${daysLeft} < 3`. See [Selection mode](#selection-mode).

> [accordion] Is there a limit to how many prototypes I can define?
>
> There's no hard limit on the number of prototypes, but for performance and maintainability reasons, it's recommended to keep the number reasonable (typically under 5-7 different prototypes).

> [accordion] What's the difference between Collection and Collection Prototype?
>
> A **Collection** is a container that iterates through an array of data items, while a **Collection Prototype** defines how each individual item should be displayed based on its properties. You need at least one Collection Prototype inside a Collection, but you can have multiple prototypes to handle different item types or states.

## Code examples

### Different prototype layouts based on item status

This example shows how to display items differently based on their status (active, pending, completed). The configuration is a simplified view of the collection's template config: styling and other properties are left out.

```javascript Process Data Setup theme={"dark"}
// Setting up process data with items of different statuses
output.put("tasks", [
  {
    "id": "task-001",
    "title": "Review application",
    "description": "Initial review of customer application",
    "status": "active",
    "priority": "high"
  },
  {
    "id": "task-002",
    "title": "Verify documents",
    "description": "Check submitted documentation for completeness",
    "status": "pending",
    "priority": "medium"
  },
  {
    "id": "task-003",
    "title": "Send confirmation",
    "description": "Email confirmation to customer",
    "status": "completed",
    "priority": "low"
  }
]);
```

```json Collection Configuration theme={"dark"}
{
  "componentIdentifier": "COLLECTION",
  "displayOptions": {
    "flowxProps": {
      "collectionSource": "tasks"
    }
  },
  "templateConfig": [
    {
      "componentIdentifier": "COLLECTION_PROTOTYPE",
      "displayOptions": {
        "flowxProps": {
          "prototypeSelectionMode": "KEY_VALUE",
          "prototypeIdentifierKey": "status",
          "prototypeIdentifierValue": "active"
        }
      },
      "templateConfig": []
    },
    {
      "componentIdentifier": "COLLECTION_PROTOTYPE",
      "displayOptions": {
        "flowxProps": {
          "prototypeSelectionMode": "KEY_VALUE",
          "prototypeIdentifierKey": "status",
          "prototypeIdentifierValue": "pending"
        }
      },
      "templateConfig": []
    },
    {
      "componentIdentifier": "COLLECTION_PROTOTYPE",
      "displayOptions": {
        "flowxProps": {
          "prototypeSelectionMode": "KEY_VALUE",
          "prototypeIdentifierKey": "status",
          "prototypeIdentifierValue": "completed"
        }
      },
      "templateConfig": []
    }
  ]
}
```

### Multiple identifier keys for complex conditions

In **Expression** mode, a prototype's **Selection condition** can combine several item fields. Here the first prototype renders high-priority unread notifications, and the second one, with no condition, is the fallback for all other items:

```javascript Process Data with Multiple Attributes theme={"dark"}
// Setting up process data with items having multiple attributes
output.put("notifications", [
  {
    "id": "notif-001",
    "message": "Your application has been approved",
    "type": "success",
    "priority": "high",
    "read": false
  },
  {
    "id": "notif-002",
    "message": "Please review updated terms",
    "type": "info",
    "priority": "low",
    "read": true
  },
  {
    "id": "notif-003",
    "message": "Action required: Missing information",
    "type": "warning",
    "priority": "high",
    "read": false
  }
]);
```

```json Multiple Prototype Configuration theme={"dark"}
{
  "componentIdentifier": "COLLECTION",
  "displayOptions": {
    "flowxProps": {
      "collectionSource": "notifications"
    }
  },
  "templateConfig": [
    {
      "componentIdentifier": "COLLECTION_PROTOTYPE",
      "displayOptions": {
        "flowxProps": {
          "prototypeSelectionMode": "EXPRESSION",
          "prototypeSelectionCondition": "${priority} === 'high' && ${read} === false"
        }
      },
      "templateConfig": []
    },
    {
      "componentIdentifier": "COLLECTION_PROTOTYPE",
      "displayOptions": {
        "flowxProps": {
          "prototypeSelectionMode": "EXPRESSION",
          "prototypeSelectionCondition": null
        }
      },
      "templateConfig": []
    }
  ]
}
```

### Nested data structures

Working with nested data in collection prototypes:

```javascript Nested Data Structure theme={"dark"}
// Setting up process data with nested objects
output.put("orders", [
  {
    "id": "order-001",
    "customer": {
      "name": "John Smith",
      "tier": "premium"
    },
    "items": [
      { "name": "Product A", "quantity": 2 },
      { "name": "Product B", "quantity": 1 }
    ],
    "status": "processing"
  },
  {
    "id": "order-002",
    "customer": {
      "name": "Jane Doe",
      "tier": "standard"
    },
    "items": [
      { "name": "Product C", "quantity": 3 }
    ],
    "status": "shipped"
  }
]);
```

```json Accessing Nested Data theme={"dark"}
{
  "componentIdentifier": "COLLECTION",
  "displayOptions": {
    "flowxProps": {
      "collectionSource": "orders"
    }
  },
  "templateConfig": [
    {
      "componentIdentifier": "COLLECTION_PROTOTYPE",
      "displayOptions": {
        "flowxProps": {
          "prototypeSelectionMode": "KEY_VALUE",
          "prototypeIdentifierKey": "customer.tier",
          "prototypeIdentifierValue": "premium"
        }
      },
      "templateConfig": [
        {
          "componentIdentifier": "TEXT",
          "displayOptions": {
            "flowxProps": {
              "text": "Premium Customer"
            }
          }
        },
        {
          "componentIdentifier": "TEXT",
          "displayOptions": {
            "flowxProps": {
              "text": "${customer.name}"
            }
          }
        },
        {
          "componentIdentifier": "COLLECTION",
          "displayOptions": {
            "flowxProps": {
              "collectionSource": "items"
            }
          },
          "templateConfig": [
            {
              "componentIdentifier": "COLLECTION_PROTOTYPE",
              "displayOptions": { "flowxProps": {} },
              "templateConfig": [
                {
                  "componentIdentifier": "TEXT",
                  "displayOptions": {
                    "flowxProps": {
                      "text": "${name} (${quantity})"
                    }
                  }
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "componentIdentifier": "COLLECTION_PROTOTYPE",
      "displayOptions": {
        "flowxProps": {
          "prototypeSelectionMode": "KEY_VALUE",
          "prototypeIdentifierKey": "customer.tier",
          "prototypeIdentifierValue": "standard"
        }
      },
      "templateConfig": []
    }
  ]
}
```

## Related components

> [card] [Collection Component](../collection)
>
> The parent component that iterates through data arrays and contains Collection Prototypes

> [card] [Event Handlers](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/event-handlers.md)
>
> Add interactivity to Collection Prototypes — run actions on click, or use Run Local Script to update local data when an item is clicked


## Related topics

- [Collection](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/collection/collection.md)
- [Layout configuration](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/layout-configuration.md)
- [FlowX.AI 5.4.0 Release Notes](https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/v5.4.0-january-2026.md)
- [FlowX.AI 5.1.4 Release Notes (LTS)](https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.4-february-2026.md)
- [UI Designer](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-designer.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.