Configure a Formatter - Nextedy Documentation

Prerequisites

Before configuring a formatter, ensure you have:

A working sheet configuration with at least one column defined
Access to edit the YAML configuration (see Download Configuration as YAML)
Familiarity with the properties available on your entity types

Define a Formatter

Formatters live in the formatters section at the root level of your sheet configuration. Each formatter is a named key containing an array of rules. Each rule pairs an expression (a condition) with a style (the visual treatment to apply when the condition is true). Step 1. Open your sheet configuration YAML and add a formatters section:

formatters:
  boldTitle:
    - expression: 'true'
      style: boldTitleStyle

Step 2. Define the referenced style in the styles section:

styles:
  boldTitleStyle:
    fontWeight: "bold"

This example defines a custom boldTitleStyle to illustrate the full define-and-reference flow. Powersheet also ships a built-in boldTitle style (see Predefined Styles); you can reference it directly without a styles entry when its default appearance suits you. The expression property accepts a JavaScript expression string. When it evaluates to true, the referenced style is applied to the cell. Using the literal 'true' means the style applies unconditionally to every cell in that column.

A formatter style is applied to the entire cell container — both its background (backgroundColor) and its text (color, fontWeight, textDecoration) — not only to the text content.

Unlike other dynamic expressions, a formatter expression is a bare boolean expression (e.g., value > 100). It does not use the () => prefix; it is evaluated as a direct boolean condition.

Apply a Formatter to a Column

Reference the formatter by name in the column’s formatter property:

columns:
  title:
    title: Title
    width: 200
    formatter: boldTitle

The formatter value must match a key defined in the formatters section exactly. If the name does not match any defined formatter, no styling is applied and no error is raised.

If you reference a formatter name that does not exist in the formatters section, Powersheet will not display an error. The column simply renders without conditional styling. Double-check that the formatter value on your column exactly matches a key under formatters.

Formatter Evaluation Flow

When a cell renders, Powersheet checks whether the column has a formatter assigned. If so, it evaluates each rule’s expression in the order they appear. The first matching rule determines the style applied.

Use the Expression Context

Inside a formatter expression, you have access to a context object that provides data about the current cell:

Context Property	Description
`context.item`	The current entity (work item) for the row
`context.value`	The value of the current cell
`context.document`	The document data object

Use dot notation to access entity properties. For example, context.item.Probability reads the Probability field of the current row’s entity.

formatters:
  highProbability:
    - expression: "context.item.Probability > 80"
      style: criticalStyle

Use Multiple Rules

A formatter can contain multiple expression-style pairs. Rules are evaluated top-to-bottom, and the first matching rule determines the applied style. Place the most specific conditions first and use a catch-all 'true' rule last for a default style:

formatters:
  severityHighlight:
    - expression: "context.value === 'Critical'"
      style: criticalStyle
    - expression: "context.value === 'Major'"
      style: majorStyle
    - expression: 'true'
      style: defaultStyle

styles:
  criticalStyle:
    backgroundColor: 'red100'
    color: 'red700'
  majorStyle:
    backgroundColor: 'orange100'
    color: 'orange700'
  defaultStyle:
    backgroundColor: 'grey100'

End your formatter with expression: 'true' to ensure every cell receives a baseline style, even when no specific condition matches. This prevents visual inconsistency between styled and unstyled cells.

Create a Read-Only Formatter

A common pattern combines a formatter with the isReadOnly column property to both visually indicate and enforce that a column cannot be edited:

formatters:
  readonly:
    - expression: 'true'
      style: readOnlyStyle

styles:
  readOnlyStyle:
    backgroundColor: 'grey100'

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

The isReadOnly: true property prevents editing at the column level, while the formatter applies a grey background to visually communicate the read-only state. Note that isReadOnly can also be overridden by document-level permissions or user access control settings.

Begin with a single formatter rule and verify it works before adding conditional expressions. Jumping straight to complex multi-rule formatters leads to hard-to-diagnose styling issues.

Define Custom Styles

Styles use CSS-like property names in camelCase. Common properties include:

Property	Example Value	Effect
`backgroundColor`	`'red100'`, `'#ffcdd2'`	Cell background color
`color`	`'red700'`, `'#d32f2f'`	Text color
`fontWeight`	`"bold"`	Bold text
`textDecoration`	`"line-through"`	Strikethrough text

Powersheet provides a set of predefined color tokens (such as red100, red700, grey100, orange100, blue100, green100, purple100, teal100, and their dark/light variants) that you can use alongside standard CSS color values.

Every style value in a formatter rule must match either a key you defined in the styles section or one of the built-in style names (none, boldTitle, readOnly, grey, red, green, blue, purple, teal, orange, and their dark/light variants). A typo in the style name causes the rule to silently produce no visual effect.

Complete YAML Example

This example shows a full configuration with two formatters applied to columns in a requirements traceability sheet:

formatters:
  readonly:
    - expression: 'true'
      style: readOnlyStyle
  priorityFormat:
    - expression: "context.value === 'Critical'"
      style: criticalStyle
    - expression: "context.value === 'High'"
      style: highStyle
    - expression: 'true'
      style: normalStyle

styles:
  readOnlyStyle:
    backgroundColor: 'grey100'
  criticalStyle:
    backgroundColor: 'red100'
    color: 'red700'
    fontWeight: "bold"
  highStyle:
    backgroundColor: 'orange100'
    color: 'orange700'
  normalStyle:
    backgroundColor: 'green100'

columns:
  outlineNumber:
    title: "#"
    width: 80
    formatter: readonly
    isReadOnly: true
  title:
    title: Title
    width: 300
    hasFocus: true
  severity:
    title: Severity
    width: 120
    formatter: priorityFormat
  systemRequirements.systemRequirement.title:
    title: System Requirement
    width: 250
    columnGroup: reqs

Advanced: Conditional Formatting

Use Expression Variables

The expression string is evaluated as JavaScript. The variable value represents the current cell value, enabling numeric comparisons and pattern matching:

formatters:
  numberRange:
    - expression: "value > 100"
      style: red
    - expression: "value > 50"
      style: orange
    - expression: 'true'
      style: green

End your formatter rules with expression: 'true' as a catch-all. Without a fallback, cells that match no rule receive no formatting.

Predefined Styles

Powersheet includes 20 built-in styles you can reference directly without defining them in the styles section:

Style Name	Description
`none`	No styling
`boldTitle`	Bold font weight
`readOnly`	Read-only visual indicator
`unsupported`	Strikethrough text on a grey background
`grey` / `darkgrey`	Grey background variants
`red` / `darkred`	Red background variants
`orange` / `darkorange`	Orange background variants
`green` / `darkgreen` / `lightgreen`	Green background variants
`blue` / `darkblue` / `lightblue`	Blue background variants
`teal` / `darkteal`	Teal background variants
`purple` / `darkpurple` / `lightpurple`	Purple background variants

You can use predefined style names directly in formatter rules:

formatters:
  statusColor:
    - expression: "value === 'Approved'"
      style: green
    - expression: "value === 'Rejected'"
      style: red
    - expression: 'true'
      style: grey

If you define a style in the styles section with the same name as a predefined style, your custom definition takes priority. The 20 predefined styles serve as defaults that are merged with your custom styles.

Verification

After saving your configuration changes:

Reload the sheet in Polarion with a full browser reload (press F5, or Ctrl+R / Cmd+R)
You should now see cells in the formatted columns displaying the conditional styles you defined
Verify that cells matching your expression conditions show the correct background color and text styling
For read-only formatters, confirm that clicking the cell does not enter edit mode and the grey background is visible

If no styling appears, check that the formatter value on the column matches a key in the formatters section, and that each style value within the formatter matches a key in the styles section.

​Prerequisites

​Define a Formatter

​Apply a Formatter to a Column

​Formatter Evaluation Flow

​Use the Expression Context

​Use Multiple Rules

​Create a Read-Only Formatter

​Define Custom Styles

​Complete YAML Example

​Advanced: Conditional Formatting

​Use Expression Variables

​Predefined Styles

​Verification

​See Also

Prerequisites

Define a Formatter

Apply a Formatter to a Column

Formatter Evaluation Flow

Use the Expression Context

Use Multiple Rules

Create a Read-Only Formatter

Define Custom Styles

Complete YAML Example

Advanced: Conditional Formatting

Use Expression Variables

Predefined Styles

Verification

See Also