Skip to main content
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

diagram 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

NameTypeDefaultDescription
titlestringBinding 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.
widthnumber or string'*'Column width. Numeric values are in pixels. String values support star-sizing (e.g. '2*' for double proportional width).
minWidthnumber150Minimum column width in pixels. Prevents the column from being resized below this value.
visiblebooleantrueControls whether the column is shown by default. Can be overridden per-view in Views.
hasFocusbooleanfalseDesignates this column as the primary focus column for its entity level. See Focus and URL Resolution.
hasUrlbooleanfalseDesignates this column to display a link to the record in the target platform. See Focus and URL Resolution.
formatterstring or string[]NoneReferences a formatter name (or array of names) from the formatters section. See Formatters.
columnGroupstringNoneAssigns the column to a visual column group. Value must be a key defined in columnGroups. See Column Groups.
multiItembooleanfalseTurns the column into a multi-item picker for many-to-many relationships. Does not create a new hierarchy level. See Multi-Item Columns.
displaystringidSpecifies 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.
renderstringNoneServer-side rendered output via a renderer or JavaScript expression. Display-only — does not affect underlying data. See Display vs. Render.
sortstringNoneDefault sort direction for this column: asc or desc. Applied in addition to the global Sort By configuration.
groupByboolean or objectfalseEnables row grouping by this column’s values. Can be a boolean or { hideCounter: boolean }. See Row Grouping.
isReadOnlybooleanfalseMakes the column read-only regardless of user permissions or document-level settings. Use a readOnly formatter separately to apply visual styling.
isRequiredbooleanfalseMarks the column as required. Creates custom validation before save — a save is blocked if this column has no value.
headerobjectNoneCustom styling for the column header. Contains a style property referencing a named style from the styles section. See Header Styling.
listobjectNoneConfiguration for picker/dropdown behavior when selecting related entities. See Picker Configuration.
frozenbooleanfalseFreezes 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.
aggregatestringsumDefines the calculation for the aggregate row. Accepted values: sum, avg, min, max, count. If omitted or invalid, defaults to sum.
filterobjectNoneDefines an initial client-side value filter. See Client-Side Filtering.
formatstringNoneData format string for numeric or date values (e.g. c0$ for currency).
formulastringNoneJavaScript arrow function for computed column values that affect the data model. See Formula Columns.
multiLinebooleantrueControls whether the cell editor supports multi-line text input.
wordWrapbooleantrueControls whether text wraps within the cell or is clipped.
typestringNoneOverrides 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 domain 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.
Aspectdisplayrender
ExecutionClient-sideServer-side (Velocity) or client-side (JS expression)
PurposeSelect which property of a referenced entity to showCustom HTML or computed output for display only
Data effectReads from the entity propertyNo effect on underlying data
SyntaxProperty name or arrow function () => ...Renderer name or JavaScript expression
EditabilityColumn 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.item.title + ' [' + context.item.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 formula, which does affect the data. 
columns:
  customSummary:
    title: Summary
    render: summaryRenderer

renderers:
  summaryRenderer: "() => `<b>${context.item.title}</b> (${context.item.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

​
Formula Columns

The formula property defines a computed column whose value is calculated from other entity properties. Unlike render, formula values affect the data model and can be saved. A formula must be a valid JavaScript arrow function starting with () =>: 
columns:
  riskScore:
    title: Risk Score
    formula: "() => context.item.Probability * context.item.Severity"
    isReadOnly: true
    width: 100
The formula has access to the current entity via context.item. For the full expression reference including the context object, see Dynamic Value Expressions.
formula computes a value that is part of the data and can be saved back. render produces display-only output. Choose formula when the calculated value needs to persist; choose render for presentation-only formatting.

​
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-propertyTypeDefaultDescription
list.searchstring[]NoneArray of property names to search when filtering entities in the picker dropdown. Enables search across the specified fields.
list.createNewbooleanfalseEnables 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-propertyTypeDescription
filter.valuesstring[]Array of values to display. All values not listed are hidden.

​
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.
ValueCalculation
sumSum of all values (default)
avgAverage of all values
minMinimum value
maxMaximum value
countCount 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
      createNew: true

  riskScore:
    title: Risk Score
    width: 80
    formula: "() => context.item.Probability * context.item.Severity"
    isReadOnly: true
    aggregate: avg

sortBy:
  - columnId: severity
    direction: desc

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

formatters:
  severityFormatter:
    expression: "context.item.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

diagram

​
Display Properties

PropertyTypeDefaultDescription
titlestringNoneDisplay label for the column header
widthnumber/string"*"Column width in pixels (number) or proportional width (string with *, e.g., "*", "2*")
minWidthnumber150Minimum column width in pixels for responsive layouts
visiblebooleantrueControls whether the column is shown in the default view. Can be overridden in views.
displaystringidSpecifies which property of a referenced entity to display. See Display Property.
renderstringNoneCustom HTML rendering function or predefined renderer name. See Render Property.

​
Behavior Properties

PropertyTypeDefaultDescription
hasFocusbooleanfalseIndicates this column receives initial focus for user interaction. Auto-configured to first editable column if not set.
isReadOnlybooleanfalsePrevents user editing of this column. To also apply visual read-only styling (greyed-out background), add a separate formatter: readOnly reference.
multiItembooleanfalseIndicates this column displays multiple related items. See Multi-Item Columns.
sortstringNoneDefault sort direction for this column. Values: "asc", "desc".
groupBybooleanfalseEnables row grouping by this column’s values

​
Styling Properties

PropertyTypeDefaultDescription
headerobjectNoneCustom styling for the column header. Contains style sub-property referencing a named style.
header.stylestringNoneName of a predefined or custom style to apply to the column header
formatterstringNoneReferences a formatter name from the formatters section to apply conditional styling
columnGroupstringNoneAssigns the column to a visual column group

​
Picker Properties

PropertyTypeDefaultDescription
listobjectNoneConfiguration for picker/dropdown lists when selecting related entities
list.searcharrayNoneArray of property names to search when filtering entities in picker dropdowns
list.displaystringNoneJavaScript function string for custom dropdown item rendering
list.createNewbooleanfalseWhether to allow creating new linked items directly from the dropdown
list.optionsstringNoneFor enum types, references a query ID from sources that provides enum values
list.valuestringNoneFor enums, the property name from the options source to use as the actual value
list.orderstringNoneFor 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

​
Example: Navigation Column

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:
SectionReference
Binding syntaxBinding Syntax
Column groupsColumn Groups
ViewsViews
FormattersFormatters
StylesStyles
Sources and expansionSources
Sort configurationSort By
Display propertyDisplay Property
Render propertyRender Property
Multi-item columnsMulti-Item Columns
Dynamic expressionsDynamic Value Expressions