Add a Column - Nextedy Documentation

Open the Sheet Configuration

Open your powersheet document in Polarion
Navigate to Menu > Configuration > Edit Sheet Configuration. This opens the sheet’s YAML configuration in the configuration editor.
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).

Add a Simple Property Column

Add a new entry under columns with a key matching a property name from your data model entity type:

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.

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.

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:

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.

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 for setting up expansion paths.

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:

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:

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

columns:
  hazards.hazard:
    title: Hazard
    render: hazardLabel
    display: 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:

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 for advanced multi-item scenarios.

Set Column Width and Sizing

Control column dimensions using width and minWidth:

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.

Apply Header Styling and Column Groups

Apply a predefined style to the column header and assign it to a column group for visual organization:

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

Define a style anchor once and reuse it across columns to keep your configuration DRY:

columns:
  title:
    title: Title
    header: &blueHeader
      style: blue
  description:
    title: Description
    header: *blueHeader

See Configure a Column Group and Apply Column Styles for the full list of style options.

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

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.

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:

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:

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.

If width is not specified, the default value is "*" — the column takes one proportional share of the available space.

Minimum Width

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

columns:
  validationTestCases.validationTestCase:
    title: Validation Test Cases
    minWidth: 200

The default minWidth is 150 pixels.

Width Strategy Decision Guide

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.

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:

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:

sortBy:
  - columnId: outlineNumber
    direction: asc
  - columnId: title
    direction: desc

Per-Column Sort Property

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

columns:
  outlineNumber:
    title: "#"
    width: 80
    sort: asc

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.

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

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.

​Column Properties Quick Reference

​Verify

​Column Sizing

​Fixed Pixel Width

​Proportional Width

​Minimum Width

​Width Strategy Decision Guide

​Default Sorting

​sortBy Array Configuration

​Multi-Column Sort

​Per-Column Sort Property

​Interactive Sorting

​See Also

Column Properties Quick Reference

Verify

Column Sizing

Fixed Pixel Width

Proportional Width

Minimum Width

Width Strategy Decision Guide

Default Sorting

sortBy Array Configuration

Multi-Column Sort

Per-Column Sort Property

Interactive Sorting

See Also