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

# Multi-Item Columns

> Multi-item columns in Nextedy POWERSHEET display and manage collections of related entities within a single column cell.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/reference/sheet-config/multi-item-columns/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=1dd6685ef15fcfd661e6b052da241ea1" alt="diagram" style={{ width: "520px", maxWidth: "100%" }} width="520" height="220" data-path="powersheet/diagrams/reference/sheet-config/multi-item-columns/diagram-1.svg" />
</Frame>

## `multiItem` Property

| Name        | Type      | Default | Description                                                                                                                 |
| ----------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `multiItem` | `boolean` | `false` | Indicates this column displays multiple related items (many-to-many relationship). Enables multi-value display and editing. |

When `multiItem` is set to `true`, the column cell renders all linked entities for the current row, rather than a single value. Users can add, remove, and browse multiple related items through a dedicated picker interface.

## When to Use Multi-Item Columns

Multi-item columns are required in these scenarios:

| Scenario                            | Example Binding Path                                                              | Description                                                                         |
| ----------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Second linked entity on same parent | `systemRequirements.systemRequirement.designRequirements.designRequirement`       | When a parent entity links to two different entity types via separate relationships |
| Verification/validation test cases  | `systemRequirements.systemRequirement.verificationTestCases.verificationTestCase` | Test case collections linked to requirements                                        |
| External references                 | `designRequirements.designRequirement.externalReferences.externalReference`       | External system links attached to design items                                      |

<Warning title="Required for Second Linked Entity Types">
  When a sheet has two work item types linked to the same parent entity (e.g., design outputs and design verifications both linked to system requirements), the **second** linked column must be declared with `multiItem: true`. This is a non-obvious requirement that commonly blocks new users during initial setup.
</Warning>

## Column Configuration Properties

The following properties apply when configuring a multi-item column:

| Name          | Type      | Default | Description                                                                                                              |
| ------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `multiItem`   | `boolean` | `false` | Enables multi-item display and editing for the column                                                                    |
| `title`       | `string`  | None    | Display label for the column header                                                                                      |
| `width`       | `number`  | None    | Column width in pixels                                                                                                   |
| `header`      | `string`  | None    | YAML anchor reference to reusable header styling configuration                                                           |
| `display`     | `string`  | `id`    | Specifies which property of the referenced entity to display. Options: `title`, `titleOrName`, or a custom property path |
| `columnGroup` | `string`  | None    | Assigns the column to a visual [column group](/powersheet/reference/sheet-config/column-groups)                          |
| `visible`     | `boolean` | `true`  | Controls whether the column is shown by default                                                                          |
| `formatter`   | `string`  | None    | References a formatter name from the [formatters](/powersheet/reference/sheet-config/formatters) section                 |
| `isReadOnly`  | `boolean` | `false` | Prevents user editing of this column (deprecated in favor of `formatter=readOnly`)                                       |

## Binding Path Syntax

Multi-item columns use dot-separated binding paths that follow the relationship chain defined in the [data model](/powersheet/reference/data-model/relationships). The path alternates between the collection navigation property and the entity type:

```
<collection>.<entityType>.<collection>.<entityType>...
```

For a full reference on binding path construction, see [Binding Syntax](/powersheet/reference/sheet-config/binding-syntax).

## Configuration Example

The following example adds an external references multi-item column to a design requirement:

```yaml theme={null}
columns:
  # Parent entity columns
  title:
    title: User Need
    width: 300
    hasFocus: true

  # Multi-item column for external references linked to design requirements
  systemRequirements.systemRequirement.designRequirements.designRequirement.externalReferences.externalReference:
    title: External References
    width: 200
    multiItem: true
    header: *blue
    display: titleOrName
```

## Sources Configuration

Multi-item columns require their expansion paths to be declared in the `sources` section. The `expand` array must include the full chain of relationships:

```yaml theme={null}
sources:
  - name: requirement
    model: rtm
    query:
      from: UserNeed
      where: "type = 'UserNeed'"
    expand:
      - name: systemRequirements
        expand:
          - name: designRequirements
            expand:
              - name: externalReferences
```

<Accordion title="Match Sources to Columns">
  Every multi-item column binding path must have a corresponding expansion path in the `sources` configuration. If the expansion is missing, the column will not load related entities.
</Accordion>

For source configuration details, see [Sources](/powersheet/reference/sheet-config/sources).

## Data Model Requirements

The entity types and relationships referenced by multi-item columns must exist in the [data model](/powersheet/reference/data-model/index):

```yaml theme={null}
domainModelTypes:
  ExternalReference:
    # entity type configuration

relationships:
  - from: ExternalReference
    to: DesignRequirement
    linkRole: relatesTo
```

Ensure the Polarion link role is configured to allow links between the relevant work item types. See [Link Roles](/powersheet/reference/data-model/link-roles) and [Relationships](/powersheet/reference/data-model/relationships).

## Export Behavior

When exporting to Excel, multi-item cells render each item on a separate line within the same cell. Comma-separated values in the sheet are converted to newline-separated lists in the exported XLSX file.

## Complete YAML Example

```yaml theme={null}
header: &blue
  style:
    background: blue
    color: white

columnGroups:
  DesignReq:
    groupName: Design Requirements
    groupStyle: blue
    headerStyle: blueHeader

columns:
  title:
    title: User Need
    width: 300
    hasFocus: true
    sort: asc

  systemRequirements.systemRequirement.title:
    title: System Requirement
    width: 250

  systemRequirements.systemRequirement.designRequirements.designRequirement.title:
    title: Design Requirement
    width: 250
    columnGroup: DesignReq

  systemRequirements.systemRequirement.designRequirements.designRequirement.externalReferences.externalReference:
    title: External References
    width: 200
    multiItem: true
    header: *blue
    display: titleOrName
    columnGroup: DesignReq

  systemRequirements.systemRequirement.verificationTestCases.verificationTestCase:
    title: Verification Tests
    width: 200
    multiItem: true
    header: *blue

sources:
  - name: requirement
    model: rtm
    query:
      from: UserNeed
      where: "type = 'UserNeed'"
    expand:
      - name: systemRequirements
        expand:
          - name: designRequirements
            expand:
              - name: externalReferences
          - name: verificationTestCases
```

## Related Pages

* [Columns](/powersheet/reference/sheet-config/columns) -- base column configuration reference
* [Binding Syntax](/powersheet/reference/sheet-config/binding-syntax) -- dot-separated path construction rules
* [Sources](/powersheet/reference/sheet-config/sources) -- data source and expansion path configuration
* [Relationships](/powersheet/reference/data-model/relationships) -- data model relationship definitions
* [Columns](/powersheet/reference/sheet-config/columns) -- full list of column-level properties

***

<LastReviewed date="2026-07-02" />