Configure Multi-Item Column - Nextedy Documentation

When to Use multiItem

Use multiItem: true when a column binding path points to a many-to-many relationship in the data model. In these cases, a single parent entity can link to multiple child entities, and those child entities can also link back to multiple parents. Common scenarios include:

Verification test cases linked to requirements
Validation test cases linked to requirements
Risk controls linked to hazards

Without multiItem: true, the column treats the binding as a single-value reference and only displays one item.

The multiItem property works with many-to-many relationships that use association entities in the data model. It does not support one-to-many relationships. If your relationship is one-to-many (a parent expanding to child rows), use a standard expansion path with nested columns instead.

Verify the Data Model Relationship

Before configuring the column, confirm that the relationship in your data model is defined as many-to-many. The relationship must use an association entity type to connect the two sides. For example, a SystemRequirement linked to multiple VerificationTestCase entities:

# Data model excerpt
relationships:
  - name: verificationTestCases
    from: SystemRequirement
    to: VerificationTestCase
    type: many-to-many

The binding path in your column configuration must follow the navigation property names defined in the data model.

Add the multiItem Column

In the columns section of your sheet configuration, add a column whose key is the full binding path to the collection navigation property. Set multiItem: true:

columns:
  verificationTestCases.verificationTestCase:
    title: Verification Test Cases
    multiItem: true
    display: title
    width: 250

Property	Type	Default	Purpose
`multiItem`	boolean	`false`	Enables multi-value display and editing for collection columns
`display`	string	`id`	Which property of the referenced entity to show (`title`, `titleOrName`, or a custom property path)

When multiItem is true, the cell renders all linked entities as a list and provides a multi-reference picker for adding or removing items.

Configure the Sources Expansion

The sources section must include an expand entry for the collection relationship. Without this expansion, the column has no data to display:

sources:
  - id: systemRequirements
    model: rtm
    query:
      from: SystemRequirement
    expand:
      - name: verificationTestCases

Each expand entry corresponds to a navigation property in the data model. The names must match exactly.

If you add multiItem: true to a column but forget the corresponding expand entry in sources, the column appears empty with no error message. Always verify that every multi-item column has a matching expansion path.

Configure the Picker Search

For multi-item columns, add a list property to control the reference picker dropdown. The list.search array defines which entity properties users can search when selecting items:

columns:
  verificationTestCases.verificationTestCase:
    title: Verification Test Cases
    multiItem: true
    display: title
    list:
      search:
        - title
        - id
      createNew: true

list.search — array of property names the picker searches against as the user types
list.createNew — set to true to allow creating a new entity directly from the picker dropdown without leaving the sheet

Add Multi-Level Multi-Item Columns

In a full traceability matrix, you may need multi-item columns at multiple levels of the hierarchy. Each level requires its own expansion path in sources:

sources:
  - id: userNeeds
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: verificationTestCases
          - name: designRequirements
            expand:
              - name: verificationTestCases

columns:
  systemRequirements.systemRequirement:
    title: System Requirements
    multiItem: true
    display: title
    list:
      search:
        - title
        - id

  systemRequirements.systemRequirement.verificationTestCases.verificationTestCase:
    title: Verification Tests (SysReq)
    multiItem: true
    display: title
    list:
      search:
        - title

  systemRequirements.systemRequirement.designRequirements.designRequirement:
    title: Design Requirements
    multiItem: true
    display: title

  systemRequirements.systemRequirement.designRequirements.designRequirement.verificationTestCases.verificationTestCase:
    title: Verification Tests (DesReq)
    multiItem: true
    display: title

Notice how each column’s binding path mirrors the nesting in the expand section. Every dot-separated segment must have a corresponding expansion entry.

When a parent entity links to two different entity types (for example, a SystemRequirement linked to both DesignRequirement and VerificationTestCase), the second linked column must use multiItem: true. This is a non-obvious requirement that consistently blocks new users during initial setup.

Optional Column Settings

You can combine multiItem with other column properties for additional control:

columns:
  verificationTestCases.verificationTestCase:
    title: Verification Test Cases
    multiItem: true
    display: title
    isReadOnly: true
    columnGroup: testCases
    visible: true
    minWidth: 200
    formatter: statusFormatter

isReadOnly — prevents editing while still displaying linked items
columnGroup — assigns the column to a visual group (see Configure a Column Group)
formatter — applies conditional styling (see Configure a Formatter)
visible — set to false to hide the column in the default view while keeping it available in named views (see Create a View)

Begin with a minimal single-item configuration and verify it works before adding multi-item columns. Jumping straight to complex multi-item setups leads to hard-to-diagnose errors. Add one multi-item column at a time and confirm each one displays data correctly before proceeding.

Verify Your Configuration

After saving the sheet configuration:

Reload the powersheet document
You should now see the multi-item column displaying linked entities as a comma-separated list in each cell
Click a cell in the multi-item column — a reference picker should appear, allowing you to search, add, or remove linked entities
If the column appears empty, check that the expand path in sources matches the column binding path exactly

The multi-reference picker behavior (including search results and the “Add New” option) depends on the server-side query configuration. If the picker returns unexpected results, verify that the data model relationship and expansion paths are correctly defined.

​When to Use multiItem

​Verify Your Configuration

​See Also

When to Use multiItem

Verify Your Configuration

See Also