Salesforce Docs Portal

Handlebars Helper Function: lookup

Dynamically access an object property or array element by specifying a variable. Unlike dot notation ({{object.property}}), which requires a literal property name, you can use lookup to determine the property name or array index at run time.

This function is based on the Handlebars.js lookup helper.

<!-- :::note AMPScript includes a Lookup function that behaves differently from this one. The Handlebars Lookup helper can search for data within a local data object only. The AMPScript Lookup function searches for data from within a marketing object. ::: -->

Availability

This helper is available in the Summer ’26 release of Marketing Cloud Next.

Syntax

{{lookup object key}}

Parameters

Parameter Type Description
object Object or Array Required. The object or array to look up a value from.
key String or Integer Required. The property name or array index to retrieve.

Return Value

The return value has the same data type as the retrieved property.

If the key doesn't exist or the index is out of bounds, the function returns undefined. An undefined property renders as an empty string.

Usage Examples

This example looks up a property in an object.

{{lookup user "name"}}

The function returns the value of the name property in the user object.

Dynamic Property Access

You can use a variable to determine which property to access. This example loops through the field names in the data object and performs a lookup on each one.

{{#each fields}}
  {{lookup ../data this}}
{{/each}}

Array Index Lookup

You can use this function to return an array element by index. This example returns the first element in the items array (the first element in an array is 0).

{{lookup items 0}}

Using Loop Index

This example uses the loop index to access the previous item.

{{#each items}}
  Previous: {{lookup ../items (subtract @index 1)}}
  Current: {{this}}
{{/each}}

Accessing Root Properties Dynamically

This example looks up a property name from the root context.

{{lookup @root propertyName}}

Nested Lookup

You can chain multiple lookup operations together. This example looks up the value of category in the data object. In that result, it returns the value of the itemName property.

{{lookup (lookup data category) itemName}}

See Also