Formatters - Nextedy Documentation

See also: Styles | Columns | Column Groups

How Formatters Work

Formatters provide conditional cell styling based on runtime data. Each formatter is a named array of rules. When a cell renders, Powersheet evaluates each rule’s expression against the current cell context. If the expression returns true, the associated style is applied to that cell.

Formatter Definition

Property	Type	Default	Description
`columns.<key>.formatter`	`string` or `string[]`	—	Name of a formatter (or array of formatter names) defined in the `formatters` section. Assigns the formatter(s) to that column.
`formatters`	object	`{}`	Top-level section containing named formatter definitions. Each key is a formatter name referenced by columns via the `formatter` property.
`formatters.<name>`	array	`[]`	Array of conditional rules for this formatter. Rules are evaluated in order; all matching rules apply their styles.
`formatters.<name>[].expression`	string	Required	JavaScript expression returning a boolean. When `true`, the associated style is applied to the cell. Has access to the `context` object.
`formatters.<name>[].style`	string or object	Required	Name of a style defined in the styles section, or an inline style object with CSS properties. Applied when the expression evaluates to `true`.

YAML Structure

formatters:
  formatterName:
    - expression: "context.item.Probability <= 99"
      style: referenceToStylesKey

The formatters section is a root-level key in the sheet configuration, alongside columns, styles, sources, views, columnGroups, renderers, and sortBy.

# Root-level sheet configuration structure
columnGroups: {}
columns: {}
sources: []
renderers: {}
formatters: {}
styles: {}
views: {}
sortBy: []

Expression Context

Every formatter expression has access to the context object. This is the same context available to renderers and dynamic value expressions.

Context Property	Type	Description
`context.document`	object	The document data object containing document-level metadata
`context.item`	object	The current entity (row) being rendered. Access entity properties by name, e.g. `context.item.Status`
`context.value`	any	The current cell value for the column being formatted

Expression Types

Formatter expressions support two notation types: Simple boolean expression (recommended):

formatters:
  riskHighlight:
    - expression: "context.item.Probability <= 99"
      style: warningStyle

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.

Inline style object (the style property supports the same CSS properties as Styles):

formatters:
  riskHighlight:
    - expression: "context.item.Severity == 'High'"
      style:
        color: red700
        backgroundColor: red100
        textDecoration: line-through

Complex JavaScript expressions in formatters are not recommended. Keep expressions simple — use straightforward property comparisons and boolean logic. Complex multi-line expressions may cause rendering issues.

Referencing Formatters from Columns

Columns reference formatters by name using the formatter property. The value must match a key defined in the formatters section.

columns:
  severity:
    title: Severity
    width: 120
    formatter: severityFormat

formatters:
  severityFormat:
    - expression: "context.item.Severity == 'Critical'"
      style: darkred
    - expression: "context.item.Severity == 'High'"
      style: red
    - expression: "context.item.Severity == 'Medium'"
      style: orange
    - expression: "context.item.Severity == 'Low'"
      style: green

The formatter column property also accepts an array of formatter names for composing multiple formatting rule sets:

columns:
  title:
    title: Title
    width: 300
    formatter:
      - boldTitle
      - statusHighlight

The formatter value on a column must exactly match a key defined in the formatters section. A mismatched name results in no formatting being applied with no error message.

Unconditional Formatters

A formatter with expression: 'true' always applies its style. This is useful for marking columns as visually distinct without conditions.

Read-Only Column Styling

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

styles:
  readOnlyStyle:
    backgroundColor: grey100

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

The isReadOnly column property and formatters serve different purposes. Use isReadOnly: true on a column to prevent editing regardless of formatting. Use a formatter with style: readOnly for visual read-only indication. The isReadOnly value may be overwritten by user permissions or global document configuration.

Bold Title Styling

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

styles:
  boldTitleStyle:
    fontWeight: 600

Conditional Formatters

Conditional formatters evaluate entity properties at render time and apply styles only when conditions are met.

Status-Based Formatting

formatters:
  statusFormat:
    - expression: "context.item.Status == 'Approved'"
      style: green
    - expression: "context.item.Status == 'Draft'"
      style: grey
    - expression: "context.item.Status == 'Rejected'"
      style: red
    - expression: "context.item.Status == 'Obsolete'"
      style: unsupported

columns:
  status:
    title: Status
    width: 120
    formatter: statusFormat

Numeric Threshold Formatting

formatters:
  probabilityFormat:
    - expression: "context.item.Probability > 80"
      style: darkred
    - expression: "context.item.Probability > 50"
      style: orange
    - expression: "context.item.Probability <= 50"
      style: green

Null / Empty Value Formatting

formatters:
  missingValue:
    - expression: "!context.value"
      style: warningStyle

styles:
  warningStyle:
    backgroundColor: orange100
    color: orange700

Multiple Rules per Formatter

A formatter can contain multiple rules. All rules are evaluated in order, and each matching rule applies its style. When multiple rules match, the later rule’s style properties override earlier ones for the same CSS property.

formatters:
  multiRule:
    - expression: "context.item.Priority == 'High'"
      style: red
    - expression: "context.item.IsBlocked == true"
      style:
        textDecoration: line-through

In this example, a high-priority blocked item receives both the red style (background and text color) and the line-through text decoration.

Predefined Styles for Formatters

Formatters reference styles by name. Powersheet provides 20 built-in styles that can be used directly without defining a custom styles section. See Styles for the full list. Commonly used predefined styles with formatters:

Style Name	Visual Effect	Typical Use
`readOnly`	Read-only cell indicator	Mark non-editable columns
`boldTitle`	`fontWeight: 600`	Emphasize key columns
`unsupported`	Grey background + `line-through`	Deprecated or unsupported values
`red`	Red text on light red background	High severity / critical status
`darkred`	Red text on darker red background	Very high severity
`orange`	Orange text on light orange background	Medium severity / warning
`darkorange`	Orange text on darker orange background	Elevated severity
`green`	Green text on light green background	Low severity / approved status
`darkgreen`	Green text on darker green background	Confirmed / verified status
`blue`	Blue text on light blue background	Informational highlights
`grey`	Grey text on light grey background	Inactive or informational
`darkgrey`	Grey text on darker grey background	Disabled or archived
`teal`	Teal text on light teal background	Secondary categorization

When a formatter references a style name, Powersheet first checks custom styles defined in the styles section, then falls back to built-in styles. A custom style with the same name as a built-in style overrides the built-in.

Row-Level Formatting

Formatters are typically applied at the column level. When a formatter is referenced from a column that spans the full row (such as an outline number column), the visual effect appears to apply to the entire row.

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

formatters:
  rowStatus:
    - expression: "context.item.Status == 'Obsolete'"
      style: unsupported

Interaction with Views

Views can override column properties including the formatter reference. A view can assign a different formatter to a column or remove formatting entirely.

views:
  Simple View:
    columns:
      severity:
        visible: true
  Risk Analysis:
    default: true
    columns:
      severity:
        formatter: severityFormat
        visible: true

The Base View is the state defined by the root columns section. Views extend the Base View by overriding specific column properties. If no views are defined or no default view is specified, the Base View is applied automatically.

Relationship Between Formatters, Styles, and Columns

The three sections work together in a clear chain:

Configuration Section	Purpose	References
`columns.<key>.formatter`	Assigns a formatter to a column	Formatter name (string or array of strings)
`formatters.<name>`	Defines conditional rules with expressions	Style name or inline style object
`styles.<name>`	Defines visual CSS properties	Color tokens (`red700`, `grey100`, etc.)

Formatter Naming Conventions

Choose formatter names that describe their purpose. Common patterns in Powersheet configurations:

Pattern	Example	Purpose
Feature-based	`severityFormat`	Format by specific domain property
State-based	`statusHighlight`	Highlight based on workflow state
Visual intent	`readonly`	Describe the visual effect
Entity-scoped	`hazardSeverity`	Format for a specific entity type’s property
Combined	`probabilityWarning`	Property name + visual intent

Complete YAML Example

A requirements traceability sheet configuration with formatters for severity, status, and read-only columns using the standard RTM entity hierarchy (UserNeed > SystemRequirement > DesignRequirement > Hazard > RiskControl):

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

  boldTitle:
    - expression: 'true'
      style: boldTitleStyle

  severityFormat:
    - expression: "context.item.Severity == 'Critical'"
      style: darkred
    - expression: "context.item.Severity == 'High'"
      style: red
    - expression: "context.item.Severity == 'Medium'"
      style: orange
    - expression: "context.item.Severity == 'Low'"
      style: green

  statusHighlight:
    - expression: "context.item.Status == 'Approved'"
      style: green
    - expression: "context.item.Status == 'Draft'"
      style: grey
    - expression: "context.item.Status == 'Rejected'"
      style: red
    - expression: "context.item.Status == 'Obsolete'"
      style: unsupported

  probabilityWarning:
    - expression: "context.item.Probability > 80"
      style: darkred
    - expression: "context.item.Probability > 50"
      style: darkorange
    - expression: "context.item.Probability <= 50"
      style: green

styles:
  readOnlyStyle:
    backgroundColor: grey100

  boldTitleStyle:
    fontWeight: 600

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

  title:
    title: Title
    width: 300
    hasFocus: true
    formatter: boldTitle

  severity:
    title: Severity
    width: 120
    formatter: severityFormat

  status:
    title: Status
    width: 120
    formatter: statusHighlight

  systemRequirements.systemRequirement.title:
    title: System Requirement
    width: 250
    columnGroup: sysReq

  systemRequirements.systemRequirement.verificationTestCases.verificationTestCase.title:
    title: Verification Test
    width: 200

  hazards.hazard.severity:
    title: Hazard Severity
    width: 130
    formatter: severityFormat

  riskControls.riskControl.probability:
    title: Residual Probability
    width: 140
    formatter: probabilityWarning

columnGroups:
  sysReq:
    groupName: System Requirements
    groupStyle: darkblue
    headerStyle: blue
    collapseTo: systemRequirements.systemRequirement.title

Best Practices

✅ Use predefined styles whenever possible rather than defining custom inline styles. The 20 built-in styles cover most color coding needs. ✅ Keep expressions simple. Use straightforward property comparisons (==, <=, >, !) and avoid multi-line or deeply nested JavaScript. ✅ Name formatters descriptively. A name like severityFormat is clearer than fmt1 when reviewing configuration. ✅ Separate concerns. Define styles in the styles section and reference them from formatters rather than using inline style objects. This promotes reuse across multiple formatters. ✅ Order rules intentionally. When multiple rules can match, later rules override earlier ones for the same CSS property. Place higher-priority styles last. ⚠️ Avoid complex expressions. Simple boolean expressions are recommended. Complex JavaScript in formatter expressions may cause unexpected behavior. ⚠️ Do not confuse formatter and render. The formatter property controls cell styling (colors, fonts). The render property controls cell content rendering (custom HTML output). See Render Property.

Conditional Formatting Chain

The full conditional formatting system connects three configuration sections in a chain: the column references a formatter by name, the formatter evaluates expressions and references a style, and the style defines the visual properties.

Style Properties Quick Reference

When defining custom styles for use with formatters, these are the supported CSS properties:

Property	Type	Default	Description
`styles.<name>.backgroundColor`	string	None	Background color token (e.g., `grey100`, `red200`)
`styles.<name>.color`	string	None	Text color token (e.g., `grey700`, `red700`)
`styles.<name>.fontWeight`	number	None	Font weight (e.g., `600`)
`styles.<name>.textDecoration`	string	None	Text decoration (e.g., `line-through`)

All Predefined Styles

All 20 predefined styles can be used in formatter rules without defining them in the styles section:

Style	Appearance
`none`	No styling
`boldTitle`	Font weight 600
`readOnly`	Read-only visual indicator
`unsupported`	Grey background with strikethrough
`grey`, `darkgrey`	Grey shades
`red`, `darkred`	Red shades
`orange`, `darkorange`	Orange shades
`green`, `darkgreen`, `lightgreen`	Green shades
`blue`, `darkblue`, `lightblue`	Blue shades
`teal`, `darkteal`	Teal shades
`purple`, `darkpurple`, `lightpurple`	Purple shades

Decision Matrix: Choosing the Right Approach

Requirement	Approach	Example
Always apply same style	Unconditional formatter with `expression: 'true'`	Read-only columns
Style based on cell value	Conditional expression	Severity coloring
Color-code column headers	Use `header.style` instead	See Styles
Color-code the column-group bar	Use `groupStyle` on the column group	See Column Groups
Color-code the headers of columns in a group	Use `headerStyle` on the column group	See Column Groups

Styles — Named style definitions referenced by formatters
Columns — Column configuration including the formatter property
Render Property — Custom content rendering (distinct from formatting)
Dynamic Value Expressions — Full reference on the context object and expression syntax
Views — View-level overrides for column formatting
Column Groups — Visual grouping with groupStyle and headerStyle
Keyboard Shortcuts — Keyboard navigation in the sheet

​How Formatters Work

​Formatter Definition

​YAML Structure

​Expression Context

​Expression Types

​Referencing Formatters from Columns

​Unconditional Formatters

​Read-Only Column Styling

​Bold Title Styling

​Conditional Formatters

​Status-Based Formatting

​Numeric Threshold Formatting

​Null / Empty Value Formatting

​Multiple Rules per Formatter

​Predefined Styles for Formatters

​Row-Level Formatting

​Interaction with Views

​Relationship Between Formatters, Styles, and Columns

​Formatter Naming Conventions

​Complete YAML Example

​Best Practices

​Conditional Formatting Chain

​Style Properties Quick Reference

​All Predefined Styles

​Decision Matrix: Choosing the Right Approach

​Related Pages

How Formatters Work

Formatter Definition

YAML Structure

Expression Context

Expression Types

Referencing Formatters from Columns

Unconditional Formatters

Read-Only Column Styling

Bold Title Styling

Conditional Formatters

Status-Based Formatting

Numeric Threshold Formatting

Null / Empty Value Formatting

Multiple Rules per Formatter

Predefined Styles for Formatters

Row-Level Formatting

Interaction with Views

Relationship Between Formatters, Styles, and Columns

Formatter Naming Conventions

Complete YAML Example

Best Practices

Conditional Formatting Chain

Style Properties Quick Reference

All Predefined Styles

Decision Matrix: Choosing the Right Approach

Related Pages