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

# Dynamic Value Expressions Reference

> Nextedy POWERSHEET configurations support **dynamic value expressions** — values resolved at runtime based on the current context such as the active document, logged-in user, URL parameters, or the source entity.

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

## Expression Notations Overview

Powersheet uses two distinct expression notations depending on the configuration file type:

| Notation               | Syntax                   | Configuration File                                      | Purpose                                     |
| ---------------------- | ------------------------ | ------------------------------------------------------- | ------------------------------------------- |
| **Context expression** | `$context.property.path` | Data model YAML (constraints)                           | Dot-notation property access, no JavaScript |
| **Dynamic value**      | `() => expression`       | Sheet configuration YAML (sources, columns, formatters) | Full JavaScript arrow function              |

<Tip title="Rule of Thumb">
  If you are editing a **data model** YAML file (`domainModelTypes`, `relationships`), use `$context`. If you are editing a **sheet configuration** YAML file (`sources`, `columns`, `formatters`), use `() =>`.
</Tip>

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

***

## Context Expression (`$context`)

Context expressions use **dot-notation** to access properties from the runtime context object. They are used exclusively in **data model configuration** — specifically in [constraint](/powersheet/reference/data-model/constraints) definitions. No JavaScript logic is supported; only direct property path access.

### Where `$context` Is Used

| Configuration Location               | Description                     |
| ------------------------------------ | ------------------------------- |
| `domainModelTypes.*.constraints`     | Entity type constraints         |
| `relationships.*.direct.constraints` | Direct relationship constraints |
| `relationships.*.back.constraints`   | Back relationship constraints   |

### Available Context Paths

| Path                                    | Type     | Description                          | Example Value                       |
| --------------------------------------- | -------- | ------------------------------------ | ----------------------------------- |
| `$context.source.type`                  | `string` | Source entity's work item type       | `"sys_req"`                         |
| `$context.source.document.id`           | `string` | Source entity's document ID          | `"Requirements/SRS"`                |
| `$context.source.document.moduleName`   | `string` | Source entity's document module name | `"UserNeedSpecification"`           |
| `$context.source.document.moduleFolder` | `string` | Source entity's document folder      | `"Requirements"`                    |
| `$context.source.document.component`    | `string` | Source entity's document component   | `"Braking"`                         |
| `$context.source.document.type`         | `string` | Source entity's document type        | `"systemRequirementsSpecification"` |
| `$context.source.document.title`        | `string` | Source entity's document title       | `"System Requirements"`             |

<Note title="Per-Row Evaluation">
  Dynamic constraints with `$context` are evaluated **per-row**. Different rows can produce different constraint values depending on their source entity's properties.
</Note>

### `$context` Examples

**Filter linked items to the same document component as the source item:**

```yaml theme={null}
relationships:
  - from: DesignRequirement
    to: SystemRequirement
    back:
      name: designRequirements
      constraints:
        load:
          document:
            component: $context.source.document.component
```

When viewing a `SystemRequirement` from the "Braking" component, only `DesignRequirement` items from "Braking" documents are loaded.

**Filter linked items to the same document as the source item:**

```yaml theme={null}
constraints:
  load:
    document:
      moduleName: $context.source.document.moduleName
      moduleFolder: $context.source.document.moduleFolder
```

**Filter by source entity's document type (pick constraint):**

```yaml theme={null}
constraints:
  pick:
    document:
      type: $context.source.document.type
```

***

## Dynamic Value (`() => expression`)

Dynamic values use **JavaScript arrow function** syntax and are used in **sheet configuration** YAML. They provide full JavaScript expressiveness for computing values, filtering data, and rendering content at runtime.

### How It Works

A `() =>` expression is a JavaScript arrow function that receives a `context` object. Powersheet evaluates the function at runtime and uses the returned value. The expression must be enclosed in quotes in the YAML configuration.

```yaml theme={null}
# General syntax
propertyName: "() => expression using context"
```

### Where `() =>` Is Used

| Sheet Configuration Property | Purpose                                          | Example                                                 |
| ---------------------------- | ------------------------------------------------ | ------------------------------------------------------- |
| `sources[].query.where`      | Filter data with dynamic predicates              | `"() => context.document.moduleName"`                   |
| `sources[].entityFactory`    | Set initial values for new items                 | `"() => context.source.type + '_VerificationTestCase'"` |
| `columns.*.formula`          | Calculate column values from other properties    | `"() => context.item.qty * context.item.price"`         |
| `columns.*.render`           | Custom HTML rendering for cells                  | `"() => '<b>' + context.value + '</b>'"`                |
| `columns.*.display`          | Override display value for navigation properties | `"() => context.item.titleOrName"`                      |
| `renderers.*`                | Named renderer definitions                       | `"() => context.value.map(...)"`                        |
| `formatters.*.expression`    | Conditional formatting expressions               | `"context.item.Probability <= 99"`                      |

<Warning title="Formula vs. Render">
  `formula` affects **persisted data** — the calculated value is saved back to the data source. Use `render` if you only need to change how a value is **displayed** without modifying the underlying data.
</Warning>

<Info title="Formatter Exception">
  Formatter expressions use a simplified syntax — they do **not** start with `() =>`. The expression is evaluated as a boolean condition directly (e.g., `"context.item.Risk > 50"`).
</Info>

***

## The Context Object

The context object provides runtime information to dynamic expressions. Its structure is hierarchical, and properties are progressively available depending on the evaluation scope.

```
context
+-- parameters          Configuration parameters (e.g. model ID)
|   +-- model           e.g. context.parameters.model
+-- user                Current logged-in user
|   +-- id, name
+-- sources             All configured data source definitions
+-- document            Current document information
|   +-- title, type, id, moduleName, moduleFolder, component
+-- tool                Current tool information
|   +-- type
+-- item                Current entity (per-cell contexts only)
|   +-- {propertyName}  e.g. context.item.StoryPoints
+-- source              Parent/source entity (relationship contexts)
|   +-- type, document.*  e.g. context.source.type
+-- entity              Current entity as a plain object
+-- value               Current cell's display value
```

### Context Availability by Location

Not all context properties are available in every expression location. The following table shows which properties are accessible where:

| Usage Location         | `context.user` | `context.sources` | `context.document` | `context.item` | `context.value` | `context.source` | `context.entity` |
| ---------------------- | :------------: | :---------------: | :----------------: | :------------: | :-------------: | :--------------: | :--------------: |
| `where` (source query) |        ✅       |         ✅         |          ✅         |        —       |        —        |         —        |         —        |
| `entityFactory`        |        ✅       |         ✅         |          —         |        —       |        —        |         ✅        |         —        |
| `formula`              |        ✅       |         ✅         |          —         |        ✅       |        ✅        |         ✅        |         ✅        |
| `render` / `renderers` |        —       |         —         |          —         |        ✅       |        ✅        |         —        |         —        |
| `formatter`            |        —       |         —         |          ✅         |        ✅       |        ✅        |         —        |         —        |
| `display`              |        —       |         —         |          —         |        ✅       |        ✅        |         ✅        |         —        |

### Context Properties Reference

| Property                        | Type     | Description                                                         |
| ------------------------------- | -------- | ------------------------------------------------------------------- |
| `context.parameters`            | `object` | Configuration parameters bag                                        |
| `context.parameters.model`      | `string` | Data model identifier for the active sheet configuration            |
| `context.user`                  | `object` | Current logged-in user information                                  |
| `context.user.id`               | `string` | User identifier                                                     |
| `context.user.name`             | `string` | Display name of the current user                                    |
| `context.sources`               | `array`  | All configured data source definitions from the sheet configuration |
| `context.document`              | `object` | Current document metadata                                           |
| `context.document.title`        | `string` | Document title                                                      |
| `context.document.type`         | `string` | Document type identifier                                            |
| `context.document.id`           | `string` | Document ID                                                         |
| `context.document.moduleName`   | `string` | LiveDoc module name                                                 |
| `context.document.moduleFolder` | `string` | LiveDoc module folder path                                          |
| `context.document.component`    | `string` | Document component identifier                                       |
| `context.tool`                  | `object` | Current tool information                                            |
| `context.tool.type`             | `string` | Tool type identifier                                                |
| `context.item`                  | `object` | Current entity being processed (per-cell only)                      |
| `context.item.{propertyName}`   | `any`    | Any property of the current entity, accessed by name                |
| `context.source`                | `object` | Parent/source entity in relationship contexts                       |
| `context.source.type`           | `string` | Parent entity's work item type                                      |
| `context.entity`                | `object` | Current entity as a plain data object                               |
| `context.value`                 | `any`    | Current cell's resolved display value                               |

***

## Expression Examples by Use Case

### Source Query Filtering (`where`)

**Filter to items in the current document module:**

```yaml theme={null}
sources:
  - id: requirements
    query:
      from: SystemRequirement
      where:
        document.moduleName:
          "==": "() => context.document.moduleName"
```

This restricts the source query to work items that belong to the same LiveDoc module as the document the sheet is embedded in.

**Filter by today's date (future items only):**

```yaml theme={null}
sources:
  - id: tasks
    query:
      from: Task
      where:
        DueDate:
          ">": "() => new Date().toISOString()"
```

<Tip title="Date Formatting">
  The resulting value must be in the correct format for the data type. For date fields, always use `.toISOString()` to produce the expected ISO 8601 string.
</Tip>

### Entity Factory (Default Values for New Items)

**Derive default values from the parent (source) entity:**

```yaml theme={null}
sources:
  - id: verificationTestCases
    query:
      from: VerificationTestCase
    entityFactory:
      title: "() => context.source.type + '_VerificationTestCase'"
      status: Draft
```

In nested or relationship-driven contexts, `entityFactory` uses `context.source` to access properties of the parent entity that triggered the row creation. Static values (like `status: Draft` above) and dynamic expressions can be mixed freely in the same `entityFactory` block.

### Column Formula (Calculated Values)

**Calculate a value from other entity properties:**

```yaml theme={null}
columns:
  totalPrice:
    formula: "() => context.item.quantity * context.item.unitPrice"
    title: Total Price
    isReadOnly: true
```

**Concatenate string properties:**

```yaml theme={null}
columns:
  fullName:
    formula: "() => `${context.item.firstName} ${context.item.lastName}`"
    title: Full Name
    isReadOnly: true
```

### Column Render (Display-Only HTML)

**Bold rendering of a cell value:**

```yaml theme={null}
columns:
  title:
    render: "() => `<b>${context.value}</b>`"
```

### Named Renderers

**Render a collection of linked items as a comma-separated list:**

```yaml theme={null}
renderers:
  linkedItems: "() => context.value.map((item) => `<b>${item.name}</b>`).join(', ')"
```

Reference the renderer by name from a column:

```yaml theme={null}
columns:
  systemRequirements.systemRequirement.title:
    render: linkedItems
```

### Column Display (Navigation Property Override)

The `display` property overrides what users see for a navigation column without changing the underlying data binding. It is the most common location for short, focused `() =>` expressions.

**Show the linked entity's title or fall back to its name:**

```yaml theme={null}
columns:
  systemRequirements.systemRequirement:
    display: "() => context.item.titleOrName"
```

`titleOrName` is a convenient idiom for entities that may have either a `title` (work items with rich descriptions) or only a `name` (lightweight reference entities).

**Show only the title of the linked entity:**

```yaml theme={null}
columns:
  systemRequirements.systemRequirement:
    display: "() => context.item.title"
```

**Show the linked entity's parent document title instead of the entity itself:**

```yaml theme={null}
columns:
  systemRequirement.document:
    display: "() => context.document.title"
```

**Compose a display string from multiple properties of the linked entity:**

```yaml theme={null}
columns:
  designRequirements.designRequirement:
    display: "() => `${context.item.id} — ${context.item.title}`"
```

This pattern is useful when a column shows a single linked item but you want a richer label (for example, an ID prefix followed by a human-readable title).

### Conditional Formatting (Formatters)

**Highlight rows where probability is below a threshold:**

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

styles:
  warningStyle:
    color: red700
    backgroundColor: red100
    textDecoration: line-through
```

Formatter expressions do **not** use the `() =>` prefix. They are evaluated directly as boolean conditions. The formatter references a [style](/powersheet/reference/sheet-config/styles) definition.

***

## Complete YAML Example

A full sheet configuration demonstrating multiple dynamic expression patterns:

```yaml theme={null}
sources:
  - id: userNeeds
    query:
      from: UserNeed
      where:
        Status:
          "!=": "() => 'Rejected'"
        DueDate:
          ">": "() => new Date().toISOString()"
        document.moduleName:
          "==": "() => context.document.moduleName"
    entityFactory:
      Status: Draft
    expand:
      - name: systemRequirements
        expand:
          - name: designRequirements

columns:
  id:
    title: ID
    width: 80
    isReadOnly: true
  title:
    title: User Need
    width: 200
    hasFocus: true
  priority:
    title: Priority
    width: 100
    formatter: highPriority
  riskScore:
    title: Risk Score
    width: 120
    formula: "() => context.item.severity * context.item.probability"
    isReadOnly: true
  systemRequirements.systemRequirement:
    title: System Requirement
    width: 220
    display: "() => context.item.titleOrName"
  systemRequirements.systemRequirement.designRequirements.designRequirement:
    title: Design Requirement
    width: 220
    display: "() => context.item.title"

renderers:
  linkedItems: "() => context.value.map((item) => `<b>${item.name}</b>`).join(', ')"

formatters:
  highPriority:
    expression: "context.item.priority === 'Critical'"
    style: criticalStyle

styles:
  criticalStyle:
    color: red700
    backgroundColor: red100

views:
  Without Design:
    columns:
      systemRequirements.systemRequirement.designRequirements.designRequirement:
        visible: false

sortBy:
  - columnId: priority
    direction: desc
  - columnId: title
    direction: asc
```

***

## Quick Reference

| I want to...                            | Notation   | Example                                                  |
| --------------------------------------- | ---------- | -------------------------------------------------------- |
| Filter relationship by source document  | `$context` | `component: $context.source.document.component`          |
| Filter query by current document module | `() =>`    | `"==": "() => context.document.moduleName"`              |
| Filter query by current date            | `() =>`    | `">": "() => new Date().toISOString()"`                  |
| Calculate column from other fields      | `() =>`    | `formula: "() => context.item.qty * context.item.price"` |
| Render custom HTML in a cell            | `() =>`    | `render: "() => '<b>' + context.value + '</b>'"`         |
| Set default from parent entity          | `() =>`    | `title: "() => context.source.type + '_TC'"`             |
| Conditionally style a cell              | expression | `expression: "context.item.Risk > 50"`                   |
| Display linked entity title-or-name     | `() =>`    | `display: "() => context.item.titleOrName"`              |
| Display the linked document title       | `() =>`    | `display: "() => context.document.title"`                |
| Render a collection as HTML             | `() =>`    | `"() => context.value.map(i => i.name).join(', ')"`      |

***

## Common Patterns and Edge Cases

### Combining Static and Dynamic Values

In `entityFactory`, static and dynamic values coexist. Only values with the `() =>` prefix are evaluated at runtime:

```yaml theme={null}
entityFactory:
  status: Draft                                    # Static — always this value
  title: "() => context.source.type + '_TC'"       # Dynamic — resolved at runtime
```

### Multiple `$context` Constraints

You can combine multiple `$context` paths in a single constraint block to narrow the filter:

```yaml theme={null}
constraints:
  load:
    document:
      moduleName: $context.source.document.moduleName
      moduleFolder: $context.source.document.moduleFolder
      component: $context.source.document.component
```

### Display Variants for the Same Navigation Column

A single navigation column can render very differently depending on the `display` expression. The same binding `systemRequirements.systemRequirement` can show:

```yaml theme={null}
# Variant A: short — falls back to name when title is missing
display: "() => context.item.titleOrName"

# Variant B: explicit — title only (blank if missing)
display: "() => context.item.title"

# Variant C: composed — ID and title together
display: "() => `${context.item.id} — ${context.item.title}`"
```

Use `display` whenever you need to change only how a linked entity appears in a cell, without changing the underlying binding path or affecting other views.

### Date Handling

Date comparisons require ISO 8601 format. Always call `.toISOString()` on Date objects:

```yaml theme={null}
where:
  CreatedDate:
    ">=": "() => new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString()"
```

The example above filters for items created within the last 7 days.

### Nested Navigation in Render Expressions

When rendering values from expanded entities, `context.value` contains the resolved data. For collections, use `.map()` and `.join()`:

```yaml theme={null}
renderers:
  testResults: "() => context.value.map((tc) => `${tc.name}: ${tc.status}`).join('<br/>')"
```

***

## Related Pages

* [Binding Syntax](/powersheet/reference/sheet-config/binding-syntax) — column key path structure and navigation patterns
* [Columns](/powersheet/reference/sheet-config/columns) — full column property reference including `formula`, `render`, and `display`
* [Formatters](/powersheet/reference/sheet-config/formatters) — conditional formatting configuration and style references
* [Styles](/powersheet/reference/sheet-config/styles) — style definitions used by formatters and column headers
* [Sources](/powersheet/reference/sheet-config/sources) — data source configuration including `query.where` and `entityFactory`
* [Render Property](/powersheet/reference/sheet-config/render-property) — detailed reference for custom rendering
* [Display Property](/powersheet/reference/sheet-config/display-property) — display override for navigation property columns
* [Constraints](/powersheet/reference/data-model/constraints) — constraint configuration where `$context` expressions are used
* [Context Expressions Reference](/powersheet/reference/data-model/context-expressions) — extended reference on `$context` paths in data models

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