> ## 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.

# Configure Multi-Item Column

> Set up a column in Nextedy POWERSHEET that displays and edits multiple related entities within a single cell using the `multiItem` property in your sheet configuration.

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>;
};

## 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.

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

<Warning title="multiItem is for many-to-many relationships">
  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.
</Warning>

<Steps>
  <Step title="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:

    ```yaml theme={null}
    # 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.
  </Step>

  <Step title="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`:

    ```yaml theme={null}
    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.
  </Step>

  <Step title="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:

    ```yaml theme={null}
    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.

    <Warning title="Missing expansion is the most common multi-item error">
      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.
    </Warning>
  </Step>

  <Step title="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:

    ```yaml theme={null}
    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
  </Step>

  <Step title="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`:

    ```yaml theme={null}
    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.

    <Warning title="Second linked entity type requires multiItem">
      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.
    </Warning>
  </Step>

  <Step title="Optional Column Settings">
    You can combine `multiItem` with other column properties for additional control:

    ```yaml theme={null}
    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](/powersheet/guides/sheet-configuration/configure-column-group))
    * **`formatter`** -- applies conditional styling (see [Configure a Formatter](/powersheet/guides/sheet-configuration/configure-formatter))
    * **`visible`** -- set to `false` to hide the column in the default view while keeping it available in named views (see [Create a View](/powersheet/guides/sheet-configuration/create-view))

    <Tip title="Start simple, extend incrementally">
      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.
    </Tip>
  </Step>
</Steps>

## Verify Your Configuration

After saving the sheet configuration:

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

<Info title="Verify in application">
  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.
</Info>

## See Also

* [Add a Column](/powersheet/guides/sheet-configuration/add-column) -- basics of column configuration and binding paths
* [Configure Sources](/powersheet/guides/sheet-configuration/configure-sources) -- defining data sources and expansion paths
* [Configure a Column Group](/powersheet/guides/sheet-configuration/configure-column-group) -- organizing multi-item columns into visual groups
* [Add External Reference Column](/powersheet/guides/sheet-configuration/add-external-reference-column) -- linking to entities outside the current document
* [Fix Multi-Item Column Errors](/powersheet/guides/troubleshooting/fix-multi-item-errors) -- troubleshooting common multi-item issues
* [Create Bidirectional Links](/powersheet/guides/data-model/create-bidirectional-links) -- setting up the data model relationships that multi-item columns depend on

<LastReviewed date="2026-06-08" />