Handlebars Reference: Looping Over Objects and Arrays

If you store user data in objects and arrays on user profiles, sometimes you may want to reference or display specific information from those objects or arrays in your dynamic content. Iterable supports several Handlebars helpers that let you do that.

# In this article

# Working with arrays

# Check whether two arrays are equal

The #eq block helper compares the size and content of two arrays. For two arrays to be considered equal, each array must have the same length and equal items, in the same order.

If the two arrays are equal, the block's content is displayed. If the two arrays are not equal, the block's content is not displayed.

# Properties

arrayName1 — The first array whose size/content you want to compare.
arrayName2 — The second array whose size/content you want to compare.
content — The content you want to display if the two arrays are equal.

# Format

{{#eq arrayName1 arrayName2}}
    content
{{/eq}}

# Example

Code	Example arrays	Output
		It's a match!

# Check whether two arrays are not equal

The #neq block helper compares the size and content of two arrays. For two arrays to be considered equal, each array must have the same length and equal items, in the same order.

If the two arrays are not equal, the block's content is displayed. If the two arrays are equal, the block's content is not displayed.

# Properties

arrayName1 — The first array whose size/content you want to compare.
arrayName2 — The second array whose size/content you want to compare.
content — The content you want to display if the two arrays are equal.

# Format

{{#eq arrayName1 arrayName2}}
    content
{{/eq}}

# Example

Code	Example arrays	Output
		Sorry... it's not a match.

# Check for an item in an array

The #ifContains block helper checks whether a specified word, character, or phrase exists within an array. If it does, the block's content is displayed. Otherwise, the content is not displayed.

# Properties

arrayName — The name of the array that contains the value(s) you want to check for.
fieldName — The name of the field that contains the value(s) you want to check for within the array.
value — The value of the field that you're interested in.

# Format

{{#ifContains arrayName `{"fieldName":"value"}`}}
<div>content</div>
{{/ifContains}}

# Example

Code	Example array	Output
		Cool shirt and jacket combo. Add some pants to complete the look!

# Display the size of an array

The size helper displays the total number of items in an array.

# Properties

arrayName — The name of the array whose size you want to display.

# Format

{{arrayName.size}}

# Example

Code	Example shoppingCartItems array	Output
		Take another look at these 3 items!

# Display all items in an array

The #each block helper lists all of the specified values in an array.

# Properties

arrayName — The name of the array that contains the values you want to display.
fieldName — The name of a field within the array whose value you want to display.
@index(optional) — Displays the index value of an item in the array.

# Format

{{#each arrayName}}
    <div>{{fieldName1}}</div>
    <div>{{fieldName2}}</div>
{{/each}}

# Example

Code	Example array	Output
		Item 1: shoes Price: 29.99 Item 2: shirt Price: 14.99 Item 3: jacket Price: 55.99

# Display the first item in an array

When using #each to loop over an array, you can optionally include the @first variable to find and display the first item in the array.

# Properties

arrayName — The name of the array whose first value you want to display.
content — The content you want to display based on the first item in the array.

# Format

{{#each arrayName}}
    {{#if @first}}
        <div>content</div>
    {{/if}}
{{/each}}

# Example

Code	Example array	Output
		Nice shoes you picked out! Ready to check out?

# Display the last item in an array

When using #each to loop over an array, you can optionally include the @last variable to find and display the last item in the array.

# Properties

arrayName — The name of the array whose last value you want to display.
content — The content you want to display based on the last item in the array.

# Format

{{#each arrayName}}
    {{#if @last}}
        <div>content</div>
    {{/if}}
{{/each}}

# Example

Code	Example array	Output
		Nice jacket you picked out! Ready to check out?

# Display a specific item within an array

You can use dot notation and index values to display a specific item within an array.

# Properties

arrayName — The name of the array that contains the item you want to display.
# — The position within the array of the item you want to display. (NOTE: The first value within an array has the index 0.)
fieldName — The name of the field within the array whose value you want to display.

# Format

{{arrayName.[#].fieldName}}

# Example

Code	Example object	Output
		jacket

# Find the smallest value in an array

The #minInList searches within a list of items in an array and finds the smallest value for a specified field.

# Properties

arrayName — The name of the array that contains the field whose smallest value you want to find.
fieldName — The name of the field whose values you want to check to identify the smallest.
content — The content you want to display when the Handlebars code is rendered.

# Format

{{#minInList arrayName "fieldName"}}
    <div>content</div>
{{/minInList}}

# Example

Code	Example shoppingCartItems array	Output
		The least expensive item in your cart is only $14.99!

# Find the largest value in an array

The #maxInList searches within a list of items in an array and finds the largest value for a specified field.

# Properties

arrayName — The name of the array that contains the field whose largest value you want to find.
fieldName — The name of the specific field within the array that contains values whose sizes you want to compare.
content — The content you want to display when the Handlebars code is rendered.

# Format

{{#maxInList arrayName "fieldName"}}
    <div>content</div>
{{/maxInList}}

# Example

Code	Example shoppingCartItems array	Output
		The most expensive item in your cart is $55.99 — treat yourself!

# Combine array values into a single string

The join helper lists all of the items in an array, connected by a specified character.

# Properties

arrayName — The name of the array that contains the values you want to display.
character — The character you want to use to connect the values of the array.
prefix (optional) — The starting character, word, or phrase you want to append to the beginning of the output.
suffix (optional) — The ending character, word, or phrase you want to append to the end of the output.

# Format

{{join arrayName "character" prefix="prefix" suffix="suffix"}}

# Example

Code	Example array	Output
		(Beginning) 816023, 969945, 1150980, 1991861, 2014924, 2049888, 2183381, 2199681, 2402054 (End)

# Working with objects

This section describes Handlebars helpers that can be used when working with objects.

# Check whether two objects are equal

The #eq helper checks whether two objects are equal. For two objects to be considered equal, they must have exactly the same set of keys and values, in the same order.

If the two objects are equal, the block's content is displayed. If the two objects are not equal, the block's content is not displayed.

# Properties

objectName1 — The name of the first object whose size/content you want to compare.
objectName2 — The name of the second object whose size/content you want to compare.
content — The content that should be displayed in the rendered output if the two objects are equal.

# Format

{{#eq objectName1 objectName2}}
    content
{{/eq}}

# Example

Code	Example arrays	Output
		It's a match!

# Check whether two objects are not equal

The #neq block helper checks whether two objects are not equal. For two objects to be considered equal, they must have exactly the same set of keys and values, in the same order.

If the two objects are not equal, the block's content is displayed. If the two objects are equal, the block's content is not displayed.

# Properties

objectName1 — The name of the first object whose size/content you want to compare.
objectName2 — The name of the second object whose size/content you want to compare.
content — The content that should be displayed in the rendered output if the two objects are not equal.

# Format

{{#neq objectName1 objectName2}}
    content
{{/neq}}

# Example

Code	Example arrays	Output
		Sorry... it's not a match.

# Display a specific item within an object

You can use dot notation and index values to display a specific item within an object.

# Properties

objectName — The name of the object that contains the item you want to display.
# — The position within the object of the item you want to display. (NOTE: The first value within an object has the index 0.)
fieldName — The name of the field within the object whose value you want to display.

# Format

{{objectName.[#].fieldName}}

# Example

Code	Example object	Output
		jacket

# Reference key/value pairs in an object

When using the each helper to loop over items in an object, you can optionally use the @key and this expressions to reference key/value pairs within the object.

# Properties

@key — The "key" component of the key/value pair you're interested in.
this — The "value" component of the key/value pair you're interested in.

# Format

{{#each objectName}}
    {{#ifContainsStr @key "keyName"}}
        {{@key}} {{this}}
    {{/ifContainsStr}}
{{/each}}

# Example

Code	Example translations object	Output
		The translation for es_ES is Hola.

# Want to learn more?

For more information about some of the topics in this article, check out these resources. Iterable Academy is open to everyone — you don't need to be an Iterable customer!

Iterable Academy

• Handlebars 101
• Advanced Handlebars

Support docs

• Handlebars Overview
• Templates Overview