Columns

This page is the exhaustive property reference for column definitions. For binding path syntax details, see Binding Syntax. For column grouping, see Column Groups. For multi-value columns, see Multi-Item Columns.

Column Configuration Hierarchy

All column types share the same set of properties described in this reference. The binding path (the YAML key) determines which entity and property the column is bound to. Every segment of a navigation path must have a corresponding expand entry in the Sources configuration.

Column Properties Reference

Name	Type	Default	Description
`title`	`string`	Binding path (e.g. `0.UserNeed.title`)	Display label for the column header. If omitted, defaults to the level index, entity type, and property name derived from the binding path.
`width`	`number` or `string`	`'*'`	Column width. Numeric values are in pixels. String values support star-sizing (e.g. `'2*'` for double proportional width).
`minWidth`	`number`	`150`	Minimum column width in pixels. Prevents the column from being resized below this value.
`visible`	`boolean`	`true`	Controls whether the column is shown by default. Can be overridden per-view in Views.
`hasFocus`	`boolean`	`false`	Designates this column as the primary focus column for its entity level. See Focus and URL Resolution.
`hasUrl`	`boolean`	`false`	Designates this column to display a link to the record in the target platform. See Focus and URL Resolution.
`formatter`	`string` or `string[]`	None	References a formatter name (or array of names) from the `formatters` section. See Formatters.
`columnGroup`	`string`	None	Assigns the column to a visual column group. Value must be a key defined in `columnGroups`. See Column Groups.
`multiItem`	`boolean`	`false`	Turns the column into a multi-item picker for many-to-many relationships. Does not create a new hierarchy level. See Multi-Item Columns.
`display`	`string`	`id`	Specifies which property of a referenced entity to display. Accepts any property path on the entity object, or a dynamic expression starting with `() =>`. See Display vs. Render.
`render`	`string`	None	Server-side rendered output via a renderer or JavaScript expression. Display-only — does not affect underlying data. See Display vs. Render.
`sort`	`string`	None	Default sort direction for this column: `asc` or `desc`. Applied in addition to the global Sort By configuration.
`groupBy`	`boolean` or `object`	`false`	Enables row grouping by this column’s values. Can be a boolean or `{ hideCounter: boolean }`. See Row Grouping.
`isReadOnly`	`boolean`	`false`	Makes the column read-only regardless of user permissions or document-level settings. Use a `readOnly` formatter separately to apply visual styling.
`isRequired`	`boolean`	`false`	Marks the column as required. Creates custom validation before save — a save is blocked if this column has no value.
`header`	`object`	None	Custom styling for the column header. Contains a `style` property referencing a named style from the `styles` section. See Header Styling.
`list`	`object`	None	Configuration for picker/dropdown behavior when selecting related entities. See Picker Configuration.
`frozen`	`boolean`	`false`	Freezes the column so it remains visible during horizontal scrolling. If multiple columns have `frozen: true`, the freeze boundary is set at the last frozen column.
`aggregate`	`string`	`sum`	Defines the calculation for the aggregate row. Accepted values: `sum`, `avg`, `min`, `max`, `count`. If omitted or invalid, defaults to `sum`.
`filter`	`object`	None	Defines an initial client-side value filter. See Client-Side Filtering.
`format`	`string`	None	Data format string for numeric or date values (e.g. `c0$` for currency).
`value`	`string`	None	JavaScript arrow function that computes the column’s content. On a bound column the result is stored in the property; on an unbound (`$`-prefixed) column it is displayed only. Either way the column is read-only. See Computed Columns.
`valueType`	`string`	`string`	Result type of an unbound column’s `value`: `string`, `number`, or `date`. Only valid on an unbound column — a bound column takes its type from the data model. See Computed Columns.
`formula`	`string`	None	Deprecated spelling of `value`. Identical behaviour; existing configurations keep working. Declaring both `value` and `formula` on one column is rejected.
`multiLine`	`boolean`	`true`	Controls whether the cell editor supports multi-line text input.
`wordWrap`	`boolean`	`true`	Controls whether text wraps within the cell or is clipped.
`type`	`string`	None	Overrides the column data type. Use `enum` for enumeration columns.

Basic Column Definition

The YAML key under columns: is the binding path — a dot-separated path from the root entity to the target property:

columns:
  title:
    title: Title
    width: 200
    hasFocus: true

  description:
    title: Description
    width: 300
    multiLine: true

  severity:
    title: Severity
    width: 100
    isReadOnly: true

Direct property columns bind to a property on the root entity type defined in the first source.

To display properties from related entities, use a navigation path. Each segment alternates between the navigation property name (the relationship) and the entity type name (from the data model):

columns:
  systemRequirements.systemRequirement.title:
    title: System Req Title
    width: 200
    hasFocus: true

  systemRequirements.systemRequirement.designRequirements.designRequirement.title:
    title: Design Req Title
    width: 200

Every navigation segment in a column binding must have a corresponding expand entry in the Sources configuration. If you define a column with binding systemRequirements.systemRequirement.designRequirements.designRequirement.title, the sources must expand both systemRequirements and designRequirements:

sources:
  - id: UserNeed
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        target: systemRequirement
        expand:
          - name: designRequirements
            target: designRequirement

For the complete binding syntax rules, see Binding Syntax.

Display vs. Render

Powersheet provides two distinct properties for controlling what a column shows. They serve different purposes and should not be confused.

Aspect	`display`	`render`
Execution	Client-side	Server-side (Velocity) or client-side (JS expression)
Purpose	Select which property of a referenced entity to show	Custom HTML or computed output for display only
Data effect	Reads from the entity property	No effect on underlying data
Syntax	Property name or arrow function `() => ...`	Renderer name or JavaScript expression
Editability	Column remains editable (unless `isReadOnly`)	Display-only output

Display Property

The display property controls which property of a referenced entity appears in the cell. It accepts:

A property name on the entity object: title, titleOrName, id, severity, or any custom property path
A dynamic expression starting with () =>: a JavaScript arrow function that returns the desired display value

columns:
  systemRequirements.systemRequirement:
    title: System Requirement
    display: titleOrName
    width: 250

  hazards.hazard:
    title: Hazard
    display: "() => context.entity.title + ' [' + context.entity.id + ']'"
    width: 300

For the full reference, see Display Property.

Render Property

The render property references a renderer defined in the renderers section or provides an inline JavaScript expression. The output is display-only HTML and does not affect the data model. This is an important difference from value on a bound column, which does affect the data — see Computed Columns.

columns:
  customSummary:
    title: Summary
    render: summaryRenderer

renderers:
  summaryRenderer: "() => `<b>${context.entity.title}</b> (${context.entity.status})`"

Each renderer has access to context:

item — the current entity
value — the cell value

For the full reference, see Render Property.

Focus and URL Resolution

The hasFocus and hasUrl properties control which column receives keyboard focus and which column displays the external platform link.

Focus Column (`hasFocus`)

Defines the primary focus column for a given entity level. When a new row is created, focus moves to this column.
If multiple columns at the same level have hasFocus: true, only the first one found is accepted.
If no column has hasFocus, the first column with hasUrl is used as the focus column.
If neither hasFocus nor hasUrl is set, the first editable column at that level receives focus.

URL Column (`hasUrl`)

Defines the column that displays a clickable link to the record in Polarion (or other target platform).
The link is only displayed if the record has a targetLink defined.
Multiple columns can have hasUrl: true to show the link in several places.
If no column has hasUrl but a column has hasFocus and is valid, the link appears there instead.
If neither is configured, the first valid column for that level displays the link.

Only string and number columns are supported for URL display. Columns with multiLine: true are not supported. Columns with custom rendering also do not show the external link.

columns:
  title:
    title: Title
    width: 200
    hasFocus: true
    hasUrl: true

Computed Columns

The value property defines a computed column whose content is calculated from an expression instead of read directly from a stored property. It must be a valid JavaScript arrow function starting with () =>. Whether the result is stored is decided by the binding key, not by value:

Binding	`value`	Result
`riskScore`	not set	Ordinary stored column, editable by the user
`riskScore`	set	Computed and stored — the result is written to the property, marks the row modified, and persists on save
`$riskScore`	set	Computed and displayed only — nothing is stored and nothing is saved
`$riskScore`	not set	Configuration error — an unbound column has no expression to derive its content from

A computed column is always read-only to the user, in both forms.

columns:
  # stored: the result is written back to the riskScore property
  riskScore:
    title: Risk Score
    value: "() => context.entity.Probability * context.entity.Severity"
    width: 100

  # display-only: no property behind it, nothing is stored
  $weightedScore:
    title: Weighted Score
    value: "() => context.entity.Probability * context.entity.Severity * 1.5"
    valueType: number
    format: "n1"
    width: 100

For the $ binding rules, see Binding Syntax. For the context object and where each expression runs, see Dynamic Value Expressions. For a step-by-step walkthrough, see Add a Computed Column.

value is about data; render is about appearance.value decides what the cell contains — and, on a bound column, what gets saved. render produces display-only HTML from whatever the cell already holds. To show a calculated value without storing it, use an unbound $ column with value, not render.

formula is deprecated. Use value.Both names mean the same thing and existing configurations keep working unchanged, but formula is deprecated — use value in new configurations. Declaring both on one column is rejected with declares both 'value' and 'formula'.

Unbound Column Constraints

An unbound column stores nothing and resolves no metadata, so these properties are rejected on it: isRequired, multiItem, and list. aggregate requires valueType: number. valueType itself is rejected on a bound column. render, renderers, format, groupBy, sort, filter, columnGroup, and the styling properties all work normally, and unbound columns take part in grouping, sorting, filtering, sheet search, and Excel export.

Multi-Item Columns

Setting multiItem: true turns a column into a multi-item picker. This is used for many-to-many relationships where multiple related entities should be displayed and selectable without creating an additional hierarchy level.

columns:
  testCases.testCase:
    title: Test Cases
    multiItem: true
    display: title
    list:
      search:
        - title
        - id

Multi-item columns do not support one-to-many relationships at this time. Use navigation path columns with expand to display one-to-many relationships as separate hierarchy levels instead.

For the full reference, see Multi-Item Columns.

Picker Configuration (`list`)

The list property configures the dropdown picker behavior when a column is bound to a reference (related entity).

Sub-property	Type	Default	Description
`list.search`	`string[]`	None	Array of property names to search when filtering entities in the picker dropdown. Enables search across the specified fields.
`list.createNew`	`boolean`	`false`	Enables or disables creating a new entity directly from the dropdown picker.

columns:
  systemRequirements.systemRequirement:
    title: System Requirement
    display: title
    list:
      search:
        - title
        - id
        - description
      createNew: true

Client-Side Filtering (`filter`)

The filter property defines an initial client-side value filter applied when the sheet loads. Only rows matching the filter values are shown; all other values are hidden.

columns:
  status:
    title: Status
    filter:
      values:
        - Open
        - In Progress

Sub-property	Type	Description
`filter.values`	`string[]`	Array of values to display. All values not listed are hidden.

Interactive sort and filter controls

Beyond the configured initial filter, users can sort and filter any column at runtime. Selecting a column in the work items tree reveals sort arrows and a funnel filter icon next to the column title:

Column header label 'Title' with vertical up/down sort arrows and a funnel filter icon next to it, used to sort or filter that column at runtime

Clicking the funnel opens a filter dialog with two tabs: Value (pick the specific values to keep visible) and Condition (define a filter expression). The dialog supports a search field, Select All, an eraser to clear the filter, and Cancel/Apply buttons.

Filter dialog opened from a column funnel icon, showing Value and Condition tabs, a Search field, Select All checkbox, individual value rows with checkboxes, an eraser clear-filter button, and Cancel/Apply buttons

Once a filter is active, the funnel icon in the column header turns green, and the toolbar shows the filtered row count (e.g. 17 / 54 rows) alongside a global funnel indicator:

Powersheet toolbar showing a 'Use Step' column with sort/filter icons, a green funnel indicating an active filter, and the row count display reading '17 / 54 rows' to confirm how many rows currently match the filter

To remove all active filters at once, use Menu > Filter & Sort > Clear all filters:

Filter & Sort submenu of the Menu dropdown showing the 'Clear all filters' entry, which removes every active column filter in a single click

Row Grouping (`groupBy`)

The groupBy property enables grouping rows by the column’s values. It supports two forms: Boolean (legacy):

columns:
  category:
    title: Category
    groupBy: true

Object with options:

columns:
  category:
    title: Category
    groupBy:
      hideCounter: true

When hideCounter is true, the item count next to each group header is hidden. By default, the group row counter visibility is controlled by the root-level showGroupRowCounter property.

Header Styling

The header property controls the visual appearance of the column header. It references a named style from the styles section.

columns:
  severity:
    title: Severity
    header:
      style: dangerHeader

styles:
  dangerHeader:
    color: red700
    backgroundColor: red100

The header.style value can be shared across columns using YAML anchors:

columns:
  probability:
    title: Probability
    header: &riskHeader
      style: riskStyle
  severity:
    title: Severity
    header: *riskHeader

The headerStyle value from the column’s columnGroup is applied by default and can be overridden by header.style on the individual column. For the full style reference, see Styles.

Frozen Columns

Setting frozen: true freezes the column so it remains visible when scrolling horizontally. If multiple columns have frozen: true, the freeze boundary is placed at the last frozen column — all columns up to and including that column are frozen.

columns:
  id:
    title: ID
    width: 80
    frozen: true
  title:
    title: Title
    width: 200
    frozen: true

Aggregate Row

The aggregate property defines a calculation displayed in the aggregate (summary) row at the bottom of the sheet.

Value	Calculation
`sum`	Sum of all values (default)
`avg`	Average of all values
`min`	Minimum value
`max`	Maximum value
`count`	Count of non-empty values

columns:
  storyPoints:
    title: Story Points
    aggregate: sum

  probability:
    title: Probability
    aggregate: avg

Column with Formatter

Reference a formatter to apply conditional styling or enforce read-only behavior:

columns:
  outlineNumber:
    title: "#"
    width: 80
    formatter: readonly
    isReadOnly: true

The referenced formatter must be defined in the formatters section:

formatters:
  readonly:
    expression: "true"
    style: readOnlyStyle

A column can also reference multiple formatters using an array:

columns:
  severity:
    title: Severity
    formatter:
      - severityHighlight
      - readonly

See Formatters for the full formatter reference.

Complete YAML Example

A complete sheet configuration demonstrating the key column properties in a requirements traceability context:

columnGroups:
  userNeeds:
    groupName: User Needs
    groupStyle: indigo
    headerStyle: indigo
  sysReqs:
    groupName: System Requirements
    groupStyle: purple
    headerStyle: purple
    collapseTo: systemRequirements.systemRequirement.title
  designReqs:
    groupName: Design Requirements
    groupStyle: orange
    headerStyle: orange

columns:
  outlineNumber:
    title: "#"
    width: 80
    sort: asc
    formatter: readonly
    isReadOnly: true
    frozen: true

  title:
    title: User Need
    width: 250
    hasFocus: true
    hasUrl: true
    columnGroup: userNeeds
    wordWrap: true

  severity:
    title: Severity
    width: 100
    columnGroup: userNeeds
    formatter: severityFormatter

  description:
    title: Description
    width: 300
    visible: false
    multiLine: true

  systemRequirements.systemRequirement.title:
    title: System Req
    width: 200
    hasFocus: true
    hasUrl: true
    columnGroup: sysReqs
    display: titleOrName
    header: &sysReqHeader
      style: purple

  systemRequirements.systemRequirement.status:
    title: Status
    width: 100
    columnGroup: sysReqs
    groupBy: true
    header: *sysReqHeader
    filter:
      values:
        - Open
        - In Review

  systemRequirements.systemRequirement.designRequirements.designRequirement.title:
    title: Design Req
    width: 200
    hasFocus: true
    columnGroup: designReqs
    display: title
    list:
      search:
        - title
        - id

  riskScore:
    title: Risk Score
    width: 80
    value: "() => context.entity.Probability * context.entity.Severity"
    aggregate: avg

  $weightedScore:
    title: Weighted Score
    width: 80
    value: "() => context.entity.Probability * context.entity.Severity * 1.5"
    valueType: number
    aggregate: avg

sortBy:
  - columnId: severity
    direction: desc

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

formatters:
  severityFormatter:
    expression: "context.entity.severity === 'Critical'"
    style: criticalStyle
  readonly:
    expression: "true"
    style: readOnlyStyle

styles:
  criticalStyle:
    color: red700
    backgroundColor: red100
  readOnlyStyle:
    backgroundColor: grey100

views:
  Without Design Reqs:
    columns:
      systemRequirements.systemRequirement.designRequirements.designRequirement.title:
        visible: false
  Critical Only:
    default: true
    columns:
      severity:
        filter:
          values:
            - Critical

Start with a minimal single-entity configuration (one source, a few direct property columns) and extend gradually. Adding navigation path columns, formatters, and views incrementally makes configuration errors easier to diagnose.

Column Property Categories

Display Properties

Property	Type	Default	Description
`title`	string	None	Display label for the column header
`width`	number/string	`"*"`	Column width in pixels (number) or proportional width (string with ``, e.g., `""`, `"2*"`)
`minWidth`	number	`150`	Minimum column width in pixels for responsive layouts
`visible`	boolean	`true`	Controls whether the column is shown in the default view. Can be overridden in views.
`display`	string	`id`	Specifies which property of a referenced entity to display. See Display Property.
`render`	string	None	Custom HTML rendering function or predefined renderer name. See Render Property.

Behavior Properties

Property	Type	Default	Description
`hasFocus`	boolean	`false`	Indicates this column receives initial focus for user interaction. Auto-configured to first editable column if not set.
`isReadOnly`	boolean	`false`	Prevents user editing of this column. To also apply visual read-only styling (greyed-out background), add a separate `formatter: readOnly` reference.
`multiItem`	boolean	`false`	Indicates this column displays multiple related items. See Multi-Item Columns.
`sort`	string	None	Default sort direction for this column. Values: `"asc"`, `"desc"`.
`groupBy`	boolean	`false`	Enables row grouping by this column’s values

Styling Properties

Property	Type	Default	Description
`header`	object	None	Custom styling for the column header. Contains `style` sub-property referencing a named style.
`header.style`	string	None	Name of a predefined or custom style to apply to the column header
`formatter`	string	None	References a formatter name from the formatters section to apply conditional styling
`columnGroup`	string	None	Assigns the column to a visual column group

Picker Properties

Property	Type	Default	Description
`list`	object	None	Configuration for picker/dropdown lists when selecting related entities
`list.search`	array	None	Array of property names to search when filtering entities in picker dropdowns
`list.display`	string	None	JavaScript function string for custom dropdown item rendering
`list.createNew`	boolean	`false`	Whether to allow creating new linked items directly from the dropdown
`list.options`	string	None	For enum types, references a query ID from sources that provides enum values
`list.value`	string	None	For enums, the property name from the options source to use as the actual value
`list.order`	string	None	For enums, the property name from the options source to sort the list by

Example: Simple Column

columns:
  id:
    width: 80
  title:
    title: Title
    width: 200
    hasFocus: true

columns:
  systemRequirements.systemRequirement.title:
    title: System Requirement
    width: 180
    columnGroup: sysReq
    header:
      style: blue

Example: Reference Column with Picker

columns:
  hazard:
    title: Hazard
    display: title
    list:
      search:
        - title
        - id

Example: Multi-Item Column

columns:
  riskControls.riskControl:
    title: Risk Controls
    width: 160
    multiItem: true
    display: title
    list:
      search:
        - title
        - id

Property Quick Reference

For related configuration sections:

Section	Reference
Binding syntax	Binding Syntax
Column groups	Column Groups
Views	Views
Formatters	Formatters
Styles	Styles
Sources and expansion	Sources
Sort configuration	Sort By
Display property	Display Property
Render property	Render Property
Multi-item columns	Multi-Item Columns
Dynamic expressions	Dynamic Value Expressions
Computed columns	Add a Computed Column

Column Configuration Hierarchy

Column Properties Reference

Basic Column Definition

Navigation Path Columns

Display vs. Render

Display Property

Render Property

Focus and URL Resolution

Focus Column (`hasFocus`)

URL Column (`hasUrl`)

Computed Columns

Unbound Column Constraints

Multi-Item Columns

Picker Configuration (`list`)

Client-Side Filtering (`filter`)

Interactive sort and filter controls

Row Grouping (`groupBy`)

Header Styling

Frozen Columns

Aggregate Row

Column with Formatter

Complete YAML Example

Column Property Categories

Display Properties

Behavior Properties

Styling Properties

Picker Properties

Example: Simple Column

Example: Navigation Column

Example: Reference Column with Picker

Example: Multi-Item Column

Property Quick Reference

​Column Configuration Hierarchy

​Column Properties Reference

​Basic Column Definition

​Navigation Path Columns

​Display vs. Render

​Display Property

​Render Property

​Focus and URL Resolution

​Focus Column (hasFocus)

​URL Column (hasUrl)

​Computed Columns

​Unbound Column Constraints

​Multi-Item Columns

​Picker Configuration (list)

​Client-Side Filtering (filter)

​Interactive sort and filter controls

​Row Grouping (groupBy)

​Header Styling

​Frozen Columns

​Aggregate Row

​Column with Formatter

​Complete YAML Example

​Column Property Categories

​Display Properties

​Behavior Properties

​Styling Properties

​Picker Properties

​Example: Simple Column

​Example: Navigation Column

​Example: Reference Column with Picker

​Example: Multi-Item Column

​Property Quick Reference

Column Configuration Hierarchy

Column Properties Reference

Basic Column Definition

Navigation Path Columns

Display vs. Render

Display Property

Render Property

Focus and URL Resolution

Focus Column (`hasFocus`)

URL Column (`hasUrl`)

Computed Columns

Unbound Column Constraints

Multi-Item Columns

Picker Configuration (`list`)

Client-Side Filtering (`filter`)

Interactive sort and filter controls

Row Grouping (`groupBy`)

Header Styling

Frozen Columns

Aggregate Row

Column with Formatter

Complete YAML Example

Column Property Categories

Display Properties

Behavior Properties

Styling Properties

Picker Properties

Example: Simple Column

Example: Navigation Column

Example: Reference Column with Picker

Example: Multi-Item Column

Property Quick Reference