Articles in this section

#filter helper

Tom Santiago
Updated

The #filter block helper iterates over an array and renders the block once for each element whose value or property matches a specified value. If no elements match, it renders an optional {{else}} block. Use it when you need to output properties of matching elements from an array of objects.

Syntax

{{#filter array value arrayProperty}} expr {{else}} expr {{/filter}}

array -- The array to filter. Required. If missing, undefined, or not an array, the helper produces no output and does not render the {{else}} block.

value -- The value to match against. Required. Matching is case-sensitive: "Custom" does not match "custom".

arrayProperty -- The property in each array element to compare. Optional. Required when array contains objects. Supports dot-paths (e.g., "details.department").

Examples

Filter line items by property value

{{#filter record.order.lineItems "custom" "tag"}}
  Custom item: {{sku}}
{{else}}
  No custom items
{{/filter}}

Input:

{
  "record": {
    "order": {
      "lineItems": [
        { "sku": "TShirt-001", "tag": "standard" },
        { "sku": "Mug-009", "tag": "custom" },
        { "sku": "SmallMug-010", "tag": "custom" },
        { "sku": "Cap-003", "tag": "standard" }
      ]
    }
  }
}

Output:

Custom item: Mug-009
Custom item: SmallMug-010

The helper renders the block once for each element where tag equals "custom". Inside the block, properties of the matching element ({{sku}}, {{tag}}) are accessible directly without a path prefix.

Render the else block when no elements match

{{#filter record.order.lineItems "express" "tag"}}
  Found express items
{{else}}
  No express items
{{/filter}}

Using the same input as above.

Output: No express items

No elements have tag equal to "express", so the {{else}} block renders.

Usage notes

  • Matching is case-sensitive: "Custom" does not match "custom".
  • Inside the block, properties of each matching element are accessible directly by name (e.g., {{sku}}, {{tag}}).
  • The helper renders once per matching element -- not once for the full array.
  • An empty array [] renders the {{else}} block. A missing, undefined, or non-array value produces no output and does not render {{else}}.
  • arrayProperty supports dot-paths for nested properties: "details.department".
  • For simple arrays (strings, numbers), omit arrayProperty and the helper matches directly against each element's value.