Handlebars Reference: Math Helpers

You can use math helpers to transform numbers contained in user or event data fields. These helpers work on fields that have the data type string, long, or double (their values must resolve to numbers).

# In this article

# Display a number as currency

The numberFormat helper can be used to display the value of a user or event data field as a price in the specified currency. In the output, values are rounded to a maximum of two decimal places, separated by either . or , (depending on the standards of the specified currency), and the corresponding currency symbol is added before or after the amount.

# Properties

fieldName — The name of the user or event data field that contains the value you want to display as currency.
locale — Checks the locale field on the user's profile — which indicates the user's locale code (geographic location and/or language preference) — to determine which currency formatting should be applied to the value of fieldName.

# Format

{{numberFormat fieldName "currency" locale}}

# Example

Code	Example shoppingCartItems.[0].price value	Example locale value	Output
	29.99	fr_FR	29,99 €

# Display a number as a percentage

The numberFormat helper can be used to display a number as a percentage.

# Properties

fieldName — The name of the user or event data field that contains the value you want to display as a percentage.

# Format

{{numberFormat fieldName "percent"}}

# Example

Code	Example courseCompletionLevel value	Output
	0.23	23%

# Specify the maximum decimal places to display in a number

You can use the numberFormat helper to shorten a number that has many decimal digits by specifying the maximumFractionDigits. This helper rounds up or down to the nearest specified decimal place.

# Properties

fieldName — The name of the user or event data field that contains the value you want to shorten. # — The maximum number of decimal place digits you want to display.

# Format

{{numberFormat fieldName maximumFractionDigits=#}}

# Example

Code	Example height value	Output
	178.0787402	178.079

# Specify the minimum amount of decimal places to display in a number

You can use the numberFormat helper to shorten a number that has many decimal digits by specifying the minimumFractionDigits. This helper rounds up or down to the nearest specified decimal place.

# Properties

fieldName — The name of the user or event data field that contains the value you want to lengthen. # — The minimum number of decimal place digits you want to display.

# Format

{{numberFormat fieldName minimumFractionDigits=#}}

# Example

Code	Example height value	Output
	178.07	178.07000

# Round a number up

You can use the numberFormat helper to round a number up. There are two options for rounding a number up: away from zero and toward positive infinity.

# Away from zero

The up rounding mode rounds a number up (away from zero) to the nearest whole number.

# Properties

fieldName — The name of the user or event data field that contains the value you want to round.

# Format

{{numberFormat fieldName "integer" roundingMode="up"}}

# Example

Code	Example averagePurchaseAmount value	Output
	50.5	51

# Toward positive infinity

The ceiling rounding mode rounds a number up toward positive infinity.

# Properties

fieldName — The name of the user or event data field that contains the value you want to round.

# Format

{{numberFormat fieldName "integer" roundingMode="ceiling"}}

# Example

Code	Example averagePurchaseAmount value	Output
	-50.5	-50

# Round a number down

You can use the numberFormat helper to round a number down. There are two options for rounding a number down: rounding toward 0 and rounding toward negative infinity.

# Toward zero

The down rounding mode rounds a number down (toward zero) to the nearest whole number.

# Properties

fieldName — The name of the user or event data field that contains the value you want to round down.

# Format

{{numberFormat fieldName "integer" roundingMode="down"}}

# Example

Code	Example averagePurchaseAmount value	Output
	50.5	50

# Toward negative infinity

The floor rounding mode rounds a number down toward negative infinity.

# Properties

fieldName — The name of the user or event data field that contains the value you want to round.

# Format

{{numberFormat fieldName "integer" roundingMode="floor"}}

# Example

Code	Example averagePurchaseAmount value	Output
	50.5	50

# Round a number to its nearest neighbor

With the half rounding options, you can round a number either up or down, whichever is closer. If the number is equidistant from its nearest neighbors (for example, 5.5 is equidistant from 5 and 6), you can specify which direction the number should be rounded: up, down, or toward the even neighbor.

# To the nearest neighbor or even number

The half_even rounding mode rounds a number toward its nearest neighbor. If the number is equidistant from its nearest neighbors, it rounds to the even neighbor.

If you include the roundingMode parameter and don't specify a rounding mode, Iterable applies the default half_even option.

# Properties

fieldName — The name of the user or event data field that contains the value you want to round.

# Format

{{numberFormat fieldName "integer" roundingMode="half_even"}}

# Example

Code	Example averagePurchaseAmount value	Output
	50.5	50

# To the nearest neighbor or up

The half_up rounding mode rounds a number toward its nearest neighbor. If the number is equidistant from its nearest neighbors, it rounds up.

# Properties

fieldName — The name of the user or event data field that contains the value you want to round.

# Format

{{numberFormat fieldName "integer" roundingMode="half_up"}}

# Example

Code	Example averagePurchaseAmount value	Output
	50.5	51

# To the nearest neighbor or down

The half_down rounding mode rounds a number toward its nearest neighbor. If the number is equidistant from its nearest neighbors, it rounds down.

# Properties

fieldName — The name of the user or event data field that contains the value you want to round.

# Format

{{numberFormat fieldName "integer" roundingMode="half_down"}}

# Example

Code	Example averagePurchaseAmount value	Output
	50.5	50

# Make long numbers easier to read

You can use the numberFormat helper to add commas to long numbers to make them easier to read.

# Properties

fieldName — The name of the user or event data field that contains the long number you want to add commas to for readability.

# Format

{{numberFormat fieldName groupingUsed=true}}

# Example

Code	Example annualRecurringRevenue value	Output
	200000000	200,000,000

# Specify a custom format for a number

# Properties

fieldName — The name of the user or event data field that contains the number you want to format. pattern — The pattern of digits, commas, and decimal places you want to apply to the number.

# Format

{{numberFormat fieldName "pattern"}}

# Example

Code	Example lifetimeUserRevenue value	Output
	1234.5678	1,234.57

# Add two numbers

You can use the math helper to add two numbers (literal numbers or the values of fields).

# Properties

fieldName — The name of the user or event data field that contains the value you want to add to.
# — The amount you want to add to the value of fieldName. (Instead of a literal number, you could enter the name of a second user or event data field containing a value.)

# Format

{{math fieldName '+' #}}

# Example

Code	Example age value	Output
	30	32

# Subtract a number from another number

You can use the math helper to subtract one number from another number (literal numbers or the values of fields).

# Properties

fieldName — The name of the user or event data field that contains the value you want to subtract from. # — The amount you want to subtract from the value of fieldName. (Instead of a literal number, you could enter the name of a second user or event data field containing a value.)

# Format

{{math fieldName '-' #}}

# Example

Code	Example age value	Output
	30	28

# Multiply two numbers

You can use the math helper to multiply two numbers (literal numbers or the values of fields).

# Properties

fieldName — The name of the user or event data field that contains the value you want to multiply. # — The amount you want to multiply the value of fieldName by. (Instead of a literal number, you could enter the name of a second user or event data field containing a value.)

# Format

{{math fieldName '*' #}}

# Example

Code	Example age value	Output
	30	90

# Divide a number by another number

You can use the math helper to divide a number by another number (literal numbers or the values of fields).

# Properties

fieldName — The name of the user or event data field that contains the value you want to divide.
# — The amount you want to divide the value of fieldName by. (Instead of a literal number, you could enter the name of a second user or event data field containing a value.)

# Format

{{math fieldName '/' #}}

# Example

Code	Example age value	Output
	30	15

# Display the remainder after dividing two numbers

You can use the math helper to display the remainder after dividing a number by another number (literal numbers or the values of fields).

# Properties

fieldName — The name of the user or event data field that contains the value you want to divide. # — The amount you want to divide the value of fieldName by. (Instead of a literal number, you could enter the name of a second user or event data field containing a value.)

# Format

{{math fieldName '%' #}}

# Example

Code	Example age value	Output
	35	1

# Check whether one number equals another number

The eq helper checks whether the value of a user or event data field equals the value of another field (or a literal number). If the two values are equal, the output is "true". If the two values are not equal, the output is "false".

When you use eq for a numeric comparison, both data fields must be of the same type: double or long.

# Properties

fieldName1 — The name of the user or event data field that contains the value you want to check against another field (alternatively, you could enter a literal number instead of the name of a field). fieldName2 — The name of the user or event data field that contains the value you want to check against the first field (alternatively, you could enter a literal number instead of the name of a field). yes="X" (Optional) — The text you want to display when the two values are equal (instead of "true").
no="Y" (Optional) — The text you want to display when the two values are not equal (instead of "false").

# Format

{{eq fieldName1 fieldName2 yes="X" no="Y"}}

# Example

Code	Example shoppingCartItems.[0].quantity value	Example shoppingCartItems.[1].quantity value	Output
	1	1	One of each

# Check whether one number is greater than another number

The gt helper checks whether the value of a user or event data field is greater than another. If the first value is greater than the second, the output is "true". If the first value is not greater than the second, the output is "false".

When you use gt for a numeric comparison, both data fields must be of the same type: double or long.

# Properties

fieldName1 — The name of the user or event data field that contains the value you want to check against another field (alternatively, you could enter a literal number instead of the name of a field). fieldName2 — The name of the user or event data field that contains the value you want to check against the first field (alternatively, you could enter a literal number instead of the name of a field). yes="X" (Optional) — The text you want to display if the first value is greater than the second value (instead of "true").
no="Y" (Optional) — The text you want to display if the first value is not greater than the second value (instead of "false").

# Format

{{gt fieldName1 fieldName2 yes="X" no="Y"}}

# Example

Code	Example values from user's profile	Output
	1, 2	More of item 2

# Check whether one number is greater than or equal to another

The gte helper checks whether the value of a user or event data field is greater than or equal to another. If the first value is greater than or equal to the second, the output is "true". If the first value is not greater than or equal to the second, the output is "false".

When you use gte for a numeric comparison, both data fields must be of the same type: double or long.

# Properties

fieldName1 — The name of the user or event data field that contains the value you want to check against another field (alternatively, you could enter a literal number instead of the name of a field). fieldName2 — The name of the user or event data field that contains the value you want to check against the first field (alternatively, you could enter a literal number instead of the name of a field). yes="X" (Optional) — The text you want to display if the first value is greater than or equal to the second value (instead of "true").
no="Y" (Optional) — The text you want to display if the first value is not greater than or equal to the second value (instead of "false").

# Format

{{gte fieldName1 fieldName2 yes="X" no="Y"}}

{{gte shoppingCartItems.[0].quantity shoppingCartItems.[1].quantity yes="More of item 1, or the quantities are equal" no= "More of item 2, or the quantities are equal"}}

# Example

# Check whether one number is less than another

The lt helper checks whether the value of a user or event data field is greater than another. If the first value is less than the second, the output is "true". If the first value is not less than the second, the output is "false".

When you use lt for a numeric comparison, both data fields must be of the same type: double or long.

# Properties

fieldName1 — The name of the user or event data field that contains the value you want to check against another field (alternatively, you could enter a literal number instead of the name of a field). fieldName2 — The name of the user or event data field that contains the value you want to check against the first field (alternatively, you could enter a literal number instead of the name of a field). yes="X" (Optional) — The text you want to display if the first value is less than the second value (instead of "true").
no="Y" (Optional) — The text you want to display if the first value is not less than the second value (instead of "false").

# Format

{{gt fieldName1 fieldName2 yes="X" no="Y"}}

{{lt shoppingCartItems.[0].quantity shoppingCartItems.[1].quantity yes="Less of item 1" no= "Less of item 2"}}

# Example

Code	Example values from user's profile	Output
	1, 2	Less of item 1

# Check whether one number is less than or equal to another

The lte block helper checks whether one number is less than or equal to another number.

When you use lte for a numeric comparison, both data fields must be of the same type: double or long.

# Properties

fieldName1 — The name of the user or event data field that contains the value you want to check against another field (alternatively, you could enter a literal number instead of the name of a field). fieldName2 — The name of the user or event data field that contains the value you want to check against the first field (alternatively, you could enter a literal number instead of the name of a field).
yes="X" (Optional) — The text you want to display if the first value is less than or equal to the second value (instead of "true").
no="Y" (Optional) — The text you want to display if the first value is not less than or equal to the second value (instead of "false").

# Format

{{lte fieldName1 fieldName2 yes="X" no="Y"}}

# Example

{{lte shoppingCartItems.[0].quantity shoppingCartItems.[1].quantity yes="Less of item 1, or the quantities are equal" no= "Less of item 2, or the quantities are equal"}}

# 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