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

# Add a Column

> Define a new column in your Nextedy POWERSHEET sheet configuration to display entity properties, linked entity fields, or multi-level expansion paths in the sheet view.

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

<Steps>
  <Step title="Open the Sheet Configuration">
    1. Open your powersheet document in Polarion
    2. Navigate to **Menu > Configuration > Edit Sheet Configuration**. This opens the sheet's YAML configuration in the configuration editor.
    3. Locate the `columns` section in the YAML configuration

    The `columns` section is an object where each key is a **binding path** that maps to an entity property or expansion path defined in your data model.

    After making changes in the configuration editor, click **Save** to persist them. The editor validates the YAML as you type and shows a status indicator (for example, **No issues found**).
  </Step>

  <Step title="Add a Simple Property Column">
    Add a new entry under `columns` with a key matching a property name from your data model entity type:

    ```yaml theme={null}
    columns:
      title:
        title: Title
        width: 200
        hasFocus: true
      description:
        title: Description
        width: 300
        wordWrap: true
      severity:
        title: Severity
        width: 100
        isReadOnly: true
    ```

    The binding path key (e.g., `title`, `description`, `severity`) must match a property name defined in the entity type of your source configuration.

    <Tip title="Set `hasFocus` on the primary editing column">
      The `hasFocus` property determines which column receives focus when a new row is created. Set it on the column users will most frequently edit first -- typically `title`. If no column has `hasFocus`, the first column with `hasUrl` is used instead. If neither is set, the first editable column receives focus.
    </Tip>
  </Step>

  <Step title="Add a Navigation Property Column">
    To display properties from related entities, use dot-separated binding paths that follow the expansion path defined in the data model sources configuration:

    ```yaml theme={null}
    columns:
      systemRequirements.systemRequirement:
        title: System Requirement
        multiItem: true
        display: title
        list:
          search:
            - title
            - id
      systemRequirements.systemRequirement.designRequirements.designRequirement:
        title: Design Requirement
        multiItem: true
        display: title
    ```

    The path `systemRequirements.systemRequirement` navigates from the root entity through the `systemRequirements` relationship (the direct navigation property) to the `SystemRequirement` entity type.

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

    <Accordion title="Ensure expansion paths match your sources configuration">
      The binding path in a column must follow an expansion path defined in your `sources` section. If you reference `systemRequirements.systemRequirement` in a column but have not defined this expansion in `sources[].expand`, the column will not display any data. See [Configure Sources](/powersheet/guides/sheet-configuration/configure-sources) for setting up expansion paths.
    </Accordion>
  </Step>

  <Step title="Configure Display for Linked Entities">
    When a column binds to a navigation property (a related entity), use `display` to specify which field of the related entity to show in the cell:

    ```yaml theme={null}
    columns:
      hazards.hazard:
        title: Hazard
        display: title
        list:
          search:
            - title
            - id
    ```

    Common `display` values:

    | Value         | Shows                              |
    | ------------- | ---------------------------------- |
    | `title`       | The entity title field             |
    | `titleOrName` | Title if available, otherwise name |
    | `id`          | The entity identifier (default)    |

    For custom rendering that combines multiple fields, use the `render` property referencing a named renderer:

    ```yaml theme={null}
    renderers:
      hazardLabel: "() => `${context.value.id}: ${context.value.title}`"

    columns:
      hazards.hazard:
        title: Hazard
        render: hazardLabel
        display: title
    ```
  </Step>

  <Step title="Configure a Multi-Item Column">
    When a relationship is one-to-many or many-to-many, set `multiItem: true` to display all linked entities in a single cell and enable the multi-item picker:

    ```yaml theme={null}
    columns:
      riskControls.riskControl:
        title: Risk Controls
        multiItem: true
        display: title
        list:
          search:
            - title
            - id
    ```

    The `multiItem: true` flag tells the sheet to render every linked entity in the cell and activates the multi-item picker for adding or removing items. See [Configure Multi-Item Column](/powersheet/guides/sheet-configuration/configure-multi-item-column) for advanced multi-item scenarios.
  </Step>

  <Step title="Set Column Width and Sizing">
    Control column dimensions using `width` and `minWidth`:

    ```yaml theme={null}
    columns:
      title:
        title: Title
        width: 250
        minWidth: 150
      status:
        title: Status
        width: "*"
    ```

    | Format | Behavior                                               |
    | ------ | ------------------------------------------------------ |
    | `200`  | Fixed width of 200 pixels                              |
    | `"*"`  | Proportional -- fills remaining space equally          |
    | `"2*"` | Proportional -- takes twice the space of `"*"` columns |

    The default width is `"*"` (proportional) and the default `minWidth` is `150` pixels.
  </Step>

  <Step title="Apply Header Styling and Column Groups">
    Apply a predefined style to the column header and assign it to a column group for visual organization:

    ```yaml theme={null}
    styles:
      reqStyle:
        color: white
        backgroundColor: indigo500

    columnGroups:
      reqs:
        groupName: Requirements
        groupStyle: reqStyle
        headerStyle: reqStyle
        collapseTo: title

    columns:
      title:
        title: Title
        width: 200
        columnGroup: reqs
        header:
          style: reqStyle
      description:
        title: Description
        width: 300
        columnGroup: reqs
    ```

    <Tip title="Use YAML anchors for reusable header styles">
      Define a style anchor once and reuse it across columns to keep your configuration DRY:

      ```yaml theme={null}
      columns:
        title:
          title: Title
          header: &blueHeader
            style: blue
        description:
          title: Description
          header: *blueHeader
      ```
    </Tip>

    See [Configure a Column Group](/powersheet/guides/sheet-configuration/configure-column-group) and [Apply Column Styles](/powersheet/guides/sheet-configuration/apply-style) for the full list of style options.
  </Step>
</Steps>

## Column Properties Quick Reference

| Property      | Type              | Default      | Description                                                                                          |
| ------------- | ----------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
| `title`       | string            | binding path | Display label in the column header                                                                   |
| `width`       | number or string  | `"*"`        | Width in pixels or proportional (`"*"`, `"2*"`)                                                      |
| `minWidth`    | number            | `150`        | Minimum width in pixels                                                                              |
| `visible`     | boolean           | `true`       | Whether the column is shown by default                                                               |
| `display`     | string            | `id`         | Which property of a referenced entity to show                                                        |
| `multiItem`   | boolean           | `false`      | Enable multi-item picker for collection relationships                                                |
| `isReadOnly`  | boolean           | `false`      | Prevent editing (may be overridden by permissions)                                                   |
| `isRequired`  | boolean           | `false`      | Require a value before save                                                                          |
| `hasFocus`    | boolean           | `false`      | Column receives initial focus on new row                                                             |
| `hasUrl`      | boolean           | `false`      | Show a link to the entity in the target platform                                                     |
| `frozen`      | boolean           | `false`      | Keep column visible when scrolling horizontally                                                      |
| `formatter`   | string            | --           | Name of a formatter for conditional styling                                                          |
| `columnGroup` | string            | --           | Assign column to a visual column group                                                               |
| `header`      | object            | --           | Custom header styling (`header.style` references a style name)                                       |
| `groupBy`     | boolean or object | `false`      | Enable row grouping by column values                                                                 |
| `sort`        | string            | --           | Default sort direction (`asc` or `desc`)                                                             |
| `aggregate`   | string            | `sum`        | Aggregate calculation: `sum`, `avg`, `min`, `max`, `count` (defaults to `sum` if omitted or invalid) |
| `filter`      | object            | --           | Initial client-side filter (`filter.values: [...]`)                                                  |
| `wordWrap`    | boolean           | `true`       | Wrap long text in the cell                                                                           |
| `multiLine`   | boolean           | `true`       | Allow multi-line text editing                                                                        |
| `format`      | string            | --           | Display format string (e.g., `c0$` for currency)                                                     |
| `render`      | string            | --           | Reference to a named renderer or JavaScript expression                                               |
| `formula`     | string            | --           | Computed column using `() => expression` syntax                                                      |
| `list`        | object            | --           | Picker configuration: `search` fields, `createNew` toggle                                            |

## Verify

After saving the sheet configuration, do a full browser reload or re-open the powersheet document -- the in-sheet refresh button only reloads data, not the configuration. You should now see:

* ✅ The new column appears in the sheet with the specified title
* ✅ Data from the bound property or expansion path is displayed correctly
* ✅ For `multiItem` columns, all linked entities appear in the cell
* ✅ Picker dialogs allow searching by the configured `list.search` fields
* ✅ Column header shows the applied style if `header.style` was set

<Info title="Verify in application">
  If the column appears but shows no data, verify that the binding path matches an expansion path defined in your `sources` configuration and that the entity type has the property defined in the data model.

  If the column does not appear at all, the binding-path key likely doesn't match a real property or expansion in the model -- an unresolvable key is silently dropped (no column, no error). Re-check the spelling of each path segment against the property and expansion names in your data model.
</Info>

## Column Sizing

Control column dimensions using fixed pixel widths, proportional star-sizing, and minimum width constraints.

### Fixed Pixel Width

Assign a number to set the column width in pixels:

```yaml theme={null}
columns:
  id:
    width: 80
  description:
    title: "Foreseeable Sequence of Events"
    width: 140
```

### Proportional Width

Use a string with `*` to define proportional width relative to other star-sized columns. The available space (after fixed-width columns are allocated) is distributed proportionally:

```yaml theme={null}
columns:
  id:
    width: 80
  title:
    width: "*"
  description:
    width: "2*"
```

In this example, after the `id` column takes 80 pixels, the remaining space is split -- `title` gets one share and `description` gets two shares.

<Note title="Default width">
  If `width` is not specified, the default value is `"*"` -- the column takes one proportional share of the available space.
</Note>

### Minimum Width

Use `minWidth` to prevent a column from shrinking below a certain pixel threshold when the sheet is resized:

```yaml theme={null}
columns:
  validationTestCases.validationTestCase:
    title: Validation Test Cases
    minWidth: 200
```

The default `minWidth` is `150` pixels.

### Width Strategy Decision Guide

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

<Tip title="Combine strategies for best results">
  Use fixed pixel widths for narrow identifier columns (`id`, `outlineNumber`), proportional `"*"` for content-heavy columns (`title`, `description`), and `minWidth` for collection columns that need guaranteed minimum space.
</Tip>

## Default Sorting

Configure the initial sort order for rows using the `sortBy` property at the top level of your sheet configuration.

### sortBy Array Configuration

Add a `sortBy` array with entries specifying a `columnId` and optional `direction`:

```yaml theme={null}
sortBy:
  - columnId: outlineNumber
    direction: asc
```

| Property    | Required | Description                                              | Default |
| ----------- | -------- | -------------------------------------------------------- | ------- |
| `columnId`  | Yes      | Dot-separated binding path to the column to sort by      | --      |
| `direction` | No       | Sort order: `"asc"` (ascending) or `"desc"` (descending) | `"asc"` |

The `columnId` value must match a binding path defined in your `columns` section.

### Multi-Column Sort

Multiple entries in the `sortBy` array create a multi-column sort. Rows are sorted by the first column, then ties are broken by the second, and so on:

```yaml theme={null}
sortBy:
  - columnId: outlineNumber
    direction: asc
  - columnId: title
    direction: desc
```

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/guides/sheet-configuration/add-column/diagram-3.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=040ac04e71d4be14d2c5c9d003937159" alt="diagram" style={{ width: "480px", maxWidth: "100%" }} width="480" height="140" data-path="powersheet/diagrams/guides/sheet-configuration/add-column/diagram-3.svg" />
</Frame>

### Per-Column Sort Property

Individual columns also support a `sort` property that defines a default sort direction for that specific column:

```yaml theme={null}
columns:
  outlineNumber:
    title: "#"
    width: 80
    sort: asc
```

<Warning title="Prefer sortBy over per-column sort">
  The global `sortBy` array gives you explicit control over sort priority. The per-column `sort` property is applied in addition to the global `sortBy` configuration, which can lead to unexpected ordering if both are used.
</Warning>

### Interactive Sorting

Users can interactively sort by clicking column headers. Powersheet supports these sort interactions:

* **Click** a column header to sort by that column (toggles ascending/descending)
* **Ctrl+Click** a column header to add it to the multi-column sort chain
* Column headers display a visual sort direction indicator when active

<Note title="Client-side sorting">
  Sorting is applied on the client side after data loads. The sort order specified in `sortBy` defines the initial view -- users can change it interactively from the toolbar.
</Note>

## See Also

* [Configure a Column Group](/powersheet/guides/sheet-configuration/configure-column-group) -- group related columns visually
* [Configure a Formatter](/powersheet/guides/sheet-configuration/configure-formatter) -- add conditional styling to columns
* [Apply Column Styles](/powersheet/guides/sheet-configuration/apply-style) -- style column headers
* [Configure Sources](/powersheet/guides/sheet-configuration/configure-sources) -- define expansion paths for navigation columns
* [Create a View](/powersheet/guides/sheet-configuration/create-view) -- create named column visibility presets
* [Configure Read-Only Column](/powersheet/guides/sheet-configuration/configure-read-only-column) -- control column editability
* [Configure Multi-Item Column](/powersheet/guides/sheet-configuration/configure-multi-item-column) -- advanced multi-item picker setup
* [Sheet Configuration Reference](/powersheet/reference/sheet-config/index) -- complete YAML property reference

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