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

# Formatters

> The `formatters` section of a Nextedy POWERSHEET sheet configuration defines named conditional formatting rules.

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>;
};

See also: [Styles](/powersheet/reference/sheet-config/styles) | [Columns](/powersheet/reference/sheet-config/columns) | [Column Groups](/powersheet/reference/sheet-config/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.

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/reference/sheet-config/formatters/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=8db98153cfee7f127e894a1e71f098b8" alt="diagram" style={{ width: "600px", maxWidth: "100%" }} width="600" height="200" data-path="powersheet/diagrams/reference/sheet-config/formatters/diagram-1.svg" />
</Frame>

## 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](/powersheet/reference/sheet-config/styles) section, **or** an inline style object with CSS properties. Applied when the expression evaluates to `true`. |

### YAML Structure

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

```yaml theme={null}
# 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](/powersheet/reference/sheet-config/render-property) and [dynamic value expressions](/powersheet/reference/sheet-config/dynamic-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):

```yaml theme={null}
formatters:
  riskHighlight:
    - expression: "context.item.Probability <= 99"
      style: warningStyle
```

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

**Inline style object** (the style property supports the same CSS properties as [Styles](/powersheet/reference/sheet-config/styles)):

```yaml theme={null}
formatters:
  riskHighlight:
    - expression: "context.item.Severity == 'High'"
      style:
        color: red700
        backgroundColor: red100
        textDecoration: line-through
```

<Warning title="Complex Expressions">
  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.
</Warning>

## Referencing Formatters from Columns

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

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

```yaml theme={null}
columns:
  title:
    title: Title
    width: 300
    formatter:
      - boldTitle
      - statusHighlight
```

<Warning title="Formatter Name Must Match">
  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.
</Warning>

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

```yaml theme={null}
formatters:
  readonly:
    - expression: 'true'
      style: readOnlyStyle

styles:
  readOnlyStyle:
    backgroundColor: grey100

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

<Tip title="Formatter vs isReadOnly">
  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.
</Tip>

### Bold Title Styling

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

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

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

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

```yaml theme={null}
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](/powersheet/reference/sheet-config/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         |

<Note title="Custom Styles Override Built-In">
  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.
</Note>

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

```yaml theme={null}
columns:
  outlineNumber:
    title: "#"
    width: 80
    formatter: rowStatus
    isReadOnly: true

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

## Interaction with Views

[Views](/powersheet/reference/sheet-config/views) can override column properties including the `formatter` reference. A view can assign a different formatter to a column or remove formatting entirely.

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

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/reference/sheet-config/formatters/diagram-2.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=dfa2d7ae5efeb17a491939a15c55f680" alt="diagram" style={{ width: "560px", maxWidth: "100%" }} width="560" height="240" data-path="powersheet/diagrams/reference/sheet-config/formatters/diagram-2.svg" />
</Frame>

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`):

```yaml theme={null}
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](/powersheet/reference/sheet-config/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.

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/reference/sheet-config/formatters/diagram-3.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=99e6d5d1bc9f1638283792a6066d79ac" alt="diagram" style={{ width: "560px", maxWidth: "100%" }} width="560" height="120" data-path="powersheet/diagrams/reference/sheet-config/formatters/diagram-3.svg" />
</Frame>

## 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](/powersheet/reference/sheet-config/styles)               |
| Color-code the column-group bar              | Use `groupStyle` on the column group              | See [Column Groups](/powersheet/reference/sheet-config/column-groups) |
| Color-code the headers of columns in a group | Use `headerStyle` on the column group             | See [Column Groups](/powersheet/reference/sheet-config/column-groups) |

## Related Pages

* [Styles](/powersheet/reference/sheet-config/styles) -- Named style definitions referenced by formatters
* [Columns](/powersheet/reference/sheet-config/columns) -- Column configuration including the `formatter` property
* [Render Property](/powersheet/reference/sheet-config/render-property) -- Custom content rendering (distinct from formatting)
* [Dynamic Value Expressions](/powersheet/reference/sheet-config/dynamic-expressions) -- Full reference on the `context` object and expression syntax
* [Views](/powersheet/reference/sheet-config/views) -- View-level overrides for column formatting
* [Column Groups](/powersheet/reference/sheet-config/column-groups) -- Visual grouping with `groupStyle` and `headerStyle`
* [Keyboard Shortcuts](/powersheet/reference/keyboard-shortcuts) -- Keyboard navigation in the sheet

***

<LastReviewed date="2026-07-02" />