> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure a Formatter

> Define named formatters in Nextedy POWERSHEET to apply conditional styling to column cells based on expression evaluation against entity data.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## 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](/powersheet/guides/sheet-configuration/download-config-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:

```yaml theme={null}
formatters:
  boldTitle:
    - expression: 'true'
      style: boldTitleStyle
```

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

```yaml theme={null}
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](#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.

<Note title="Styles apply to the whole cell">
  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.
</Note>

<Note title="Formatter syntax difference">
  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.
</Note>

## Apply a Formatter to a Column

Reference the formatter by name in the column's `formatter` property:

```yaml theme={null}
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.

<Warning title="Mismatched formatter names fail silently">
  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`.
</Warning>

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

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/guides/sheet-configuration/configure-formatter/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=27d571d7af325714f6b35832652bdfb8" alt="diagram" style={{ width: "520px", maxWidth: "100%" }} width="520" height="170" data-path="powersheet/diagrams/guides/sheet-configuration/configure-formatter/diagram-1.svg" />
</Frame>

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

```yaml theme={null}
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:

```yaml theme={null}
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'
```

<Tip title="Use a catch-all rule for consistent appearance">
  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.
</Tip>

## 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:

```yaml theme={null}
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.

<Tip title="Start simple, extend incrementally">
  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.
</Tip>

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

<Warning title="Nonexistent style references fail silently">
  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.
</Warning>

## Complete YAML Example

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

```yaml theme={null}
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:

```yaml theme={null}
formatters:
  numberRange:
    - expression: "value > 100"
      style: red
    - expression: "value > 50"
      style: orange
    - expression: 'true'
      style: green
```

<Note title="Always include a fallback rule">
  End your formatter rules with `expression: 'true'` as a catch-all. Without a fallback, cells that match no rule receive no formatting.
</Note>

### 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:

```yaml theme={null}
formatters:
  statusColor:
    - expression: "value === 'Approved'"
      style: green
    - expression: "value === 'Rejected'"
      style: red
    - expression: 'true'
      style: grey
```

<Warning title="Custom styles override predefined names">
  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.
</Warning>

## Verification

After saving your configuration changes:

1. Reload the sheet in Polarion with a full browser reload (press `F5`, or `Ctrl+R` / `Cmd+R`)
2. You should now see cells in the formatted columns displaying the conditional styles you defined
3. Verify that cells matching your expression conditions show the correct background color and text styling
4. 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.

## See Also

* [Apply Column Styles](/powersheet/guides/sheet-configuration/apply-style) -- apply cell, header, and column-group styles, including styling the headers of columns within a group
* [Configure a Column Group](/powersheet/guides/sheet-configuration/configure-column-group) -- visually organize related columns with shared styling
* [Configure Read-Only Column](/powersheet/guides/sheet-configuration/configure-read-only-column) -- enforce read-only behavior at the column level
* [Add a Column](/powersheet/guides/sheet-configuration/add-column) -- basic column configuration properties
* [Create a View](/powersheet/guides/sheet-configuration/create-view) -- define named view presets with different column visibility
* [Keyboard Shortcuts](/powersheet/reference/keyboard-shortcuts) -- row grouping, column freezing, and other in-sheet shortcuts
* [Sheet Configuration Reference](/powersheet/reference/sheet-config/index) -- complete property reference for sheet configuration YAML

<LastReviewed date="2026-06-08" />