Skip to main content

​
Step 1: Open the Sheet Configuration

  1. Open your powersheet document in Polarion
  2. Navigate to Menu > Configuration > Edit Document Configuration
  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 domain model.

​
Step 2: Add a Simple Property Column

Add a new entry under columns with a key matching a property name from your domain 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.

​
Step 3: Add a Navigation Property Column

To display properties from related entities, use dot-separated binding paths that follow the expansion path defined in the domain 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. diagram
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.

​
Step 4: 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:
ValueShows
titleThe entity title field
titleOrNameTitle if available, otherwise name
idThe 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

​
Step 5: 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
      createNew: true
Setting list.createNew: true allows users to create a new linked entity directly from the picker dropdown. See Configure Multi-Item Column for advanced multi-item scenarios.

​
Step 6: Set Column Width and Sizing

Control column dimensions using width and minWidth: 
columns:
  title:
    title: Title
    width: 250
    minWidth: 150
  status:
    title: Status
    width: "*"
FormatBehavior
200Fixed 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 7: 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

PropertyTypeDefaultDescription
titlestringbinding pathDisplay label in the column header
widthnumber or string"*"Width in pixels or proportional ("*", "2*")
minWidthnumber150Minimum width in pixels
visiblebooleantrueWhether the column is shown by default
displaystringidWhich property of a referenced entity to show
multiItembooleanfalseEnable multi-item picker for collection relationships
isReadOnlybooleanfalsePrevent editing (may be overridden by permissions)
isRequiredbooleanfalseRequire a value before save
hasFocusbooleanfalseColumn receives initial focus on new row
hasUrlbooleanfalseShow a link to the entity in the target platform
frozenbooleanfalseKeep column visible when scrolling horizontally
formatterstring—Name of a formatter for conditional styling
columnGroupstring—Assign column to a visual column group
headerobject—Custom header styling (header.style references a style name)
groupByboolean or objectfalseEnable row grouping by column values
sortstring—Default sort direction (asc or desc)
aggregatestring—Aggregate calculation: sum, avg, min, max, count
filterobject—Initial client-side filter (filter.values: [...])
wordWrapbooleantrueWrap long text in the cell
multiLinebooleantrueAllow multi-line text editing
formatstring—Display format string (e.g., c0$ for currency)
renderstring—Reference to a named renderer or JavaScript expression
formulastring—Computed column using () => expression syntax
listobject—Picker configuration: search fields, createNew toggle

​
Verify

After saving the sheet configuration, reload the powersheet document. 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 domain 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

diagram
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
PropertyRequiredDescriptionDefault
columnIdYesDot-separated binding path to the column to sort by—
directionNoSort 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
diagram

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

​
See Also