Filters

This reference article provides an overview of filters in Liquid, and covers which filters are supported by Braze. Looking for ideas on how you can use these filters? Check out our Liquid Use Case Library.

Filters are how you can modify the output of numbers, strings, variables, and objects in Liquid. You can use filters to reformat static or dynamic text, such as changing a string from lowercase to uppercase or to perform mathematical operations, like addition or division.

Filters must be placed within an output tag {{ }} and are denoted by a pipe character |.

1
{{"Big Sale" | upcase}}
1
BIG SALE

In the example above, Big Sale is a string, and upcase is the filter being applied.

You can use multiple filters on one output. They are applied from left to right.

1
 {{ "Big Sale" | upcase | remove: “BIG” }}
1
SALE

Array Filters

Array filters are used to change the output of arrays.

Filter Definition Supported
join Joins the elements of an array with the character passed as the parameter. The result is a single string. ✅ Yes
first Returns the first element of an array. In a custom attribute array, this is the most recently added value. ✅ Yes
last Returns the last element of an array. In a custom attribute array, this is the oldest added value. ✅ Yes
concat Combines an array with another array. ⛔ No
index Returns the item at the specified index location in an array. The first item in an array is referenced with [0]. ✅ Yes
map Accepts an array element’s attribute as a parameter and creates an array out of each array element’s value. ✅ Yes
reverse Reverses the order of the items in an array. ✅ Yes
size Returns the size of a string (the number of characters) or an array (the number of elements). ✅ Yes
sort Sorts the elements of an array by a given attribute of an element in the array. ✅ Yes
uniq Removes any duplicate instances of elements in an array. ✅ Yes

Color Filters

Color filters are not supported in Braze.

Font Filters

Font filters are not supported in Braze.

Math Filters

Math filters allow you to perform mathematical operations. Remember—if you use multiple filters on one output, they are applied from left to right.

Filter Definition Supported
abs Returns the absolute value of a number. ✅ Yes
at_most Limits a number to a maximum value. ⛔ No
at_least Limits a number to a minimum value. ⛔ No
ceil Rounds an output up to the nearest integer. ✅ Yes
divided_by Divides an output by a number. The output is rounded down to the nearest integer. Check out the tip below to prevent rounding. ✅ Yes
floor Rounds an output down to the nearest integer. ✅ Yes
minus Subtracts a number from an output. ✅ Yes
plus Adds a number to an output. ✅ Yes
round Rounds the output to the nearest integer or specified number of decimals. ✅ Yes
times Multiplies an output by a number. ✅ Yes
modulo Divides an output by a number and returns the remainder. ✅ Yes

Mathematical Operations with Custom Attributes

Keep in mind that you can’t perform mathematical operations between two custom attributes.

1
{{custom_attribute.${current_rewards_balance} | plus: {{custom_attribute.${giftcard_balance}}}}}

This example wouldn’t work because you can’t reference multiple custom attributes in one line of Liquid. Instead, you would need to assign a variable to at least one of these values before the math functions take place. Adding two custom attributes together would require two lines of Liquid:

  1. One to assign the custom attribute to a variable,
  2. One to perform the addition.

For example, let’s say we want to calculate a user’s current balance by adding their gift card balance and rewards balance. First, use the assign tag to substitute the custom attribute of current_rewards_balance with the term “balance”. This means that you now have a variable named balance, which you can manipulate.

1
{% assign balance = {{custom_attribute.${current_rewards_balance}}} %}

Next, use the plus filter to combine each user’s gift card balance with their rewards balance, signified by the {{balance}} object.

1
2
{% assign balance = {{custom_attribute.${current_rewards_balance}}} %}
You have ${{custom_attribute.${giftcard_balance} | plus: {{balance}}}} to spend!
1
You have $35 to spend!

Money Filters

If you’re updating a user on their purchase, an account balance, or anything regarding money, you should use money filters. Money filters ensure that your decimals are in the proper place and that no piece of your update is lost (like that pesky 0 at the end).

Filter Definition Supported
money Formats numbers to ensure that decimals are in the proper place, and zeros are not dropped off the end of any numbers. ✅ Yes
money_with_currency Formats numbers with the currency symbol. ✅ Yes
money_without_trailing_zeros Formats numbers to exclude the decimal separator (either . or ,) and trailing zeros. If there are no trailing zeros, then this filter behaves like the money filter. ✅ Yes
money_without_currency Formats numbers without the currency symbol. ⛔ No

Shopify Money Filter vs Braze Money Filter

In the event you are inputting a custom attribute (like account_balance), you should always use the money filter to ensure that your decimals are in the proper place, and zeros are not dropped off the end of any numbers, as shown below:

1
${{custom_attribute.${account_balance} | money}}
WITH THE MONEY FILTER WITHOUT THE MONEY FILTER
With money filter Without money filter
Where account_balance is input at 17.8. Where account_balance is input at 17.8.

The money filter in Braze differs from Shopify in that it does not automatically apply decimal points according to a preset setting. For example, take the following scenario where rewards_redeemed contains a value of 145:

1
${{event_properties.${rewards_redeemed} | money }}
1
$145.00

According to Shopify’s money filter, this should have an output of $1.45, however in Braze, this will have an output of $145.00. As a workaround, we can use the divided_by filter to manipulate the number into a decimal, before applying the money filter:

1
${{event_properties.${rewards_redeemed} | divided_by: 100.00 | money }}
1
$1.45

String Filters

String filters are used to manipulate the outputs and variables of strings. Strings are a combination of alphanumeric characters and must be wrapped in straight quotes.

Filter Description Supported
append Appends characters to a string. ✅ Yes
camelcase Converts a string into CamelCase. ⛔ No
capitalize Capitalizes the first word in a string. ✅ Yes
downcase Converts a string into lowercase. ✅ Yes
escape Escapes a string. ✅ Yes
handle/handleize Formats a string into a handle. ⛔ No
md5 Converts a string into an MD5 hash. Refer to Encoding Filters for more. ✅ Yes
sha1 Converts a string into a SHA-1 hash. Refer to Encoding Filters for more. ✅ Yes
hmac_sha1_hex
(previously hmac_sha_1)
Converts a string into a SHA-1 hash using a hash message authentication code (HMAC). Pass the secret key for the message as a parameter to the filter. Refer to Encoding Filters for more. ✅ Yes
hmac_sha256 Converts a string into a SHA-256 hash using a hash message authentication code (HMAC). Pass the secret key for the message as a parameter to the filter. ✅ Yes
newline_to_br Inserts a <br> linebreak HTML tag in front of each line break in a string. ✅ Yes
pluralize Outputs the singular or plural version of an English string based on the value of a number. ⛔ No
prepend Prepends characters to a string. ✅ Yes
remove Removes all occurrences of a substring from a string. ✅ Yes
remove_first Removes only the first occurrence of a substring from a string. ✅ Yes
replace Replaces all occurrences of a string with a substring. ✅ Yes
replace_first Replaces the first occurrence of a string with a substring. ✅ Yes
slice The slice filter returns a substring, starting at the specified index. ✅ Yes
split The split filter takes on a substring as a parameter. The substring is used as a delimiter to divide a string into an array. ✅ Yes
strip Strips tabs, spaces, and newlines (all whitespace) from the left and right side of a string. ✅ Yes
lstrip Strips tabs, spaces, and newlines (all whitespace) from the left side of a string. ⛔ No
rstrip Strips tabs, spaces, and newlines (all whitespace) from the right side of a string. ⛔ No
strip_html Strips all HTML tags from a string. ✅ Yes
strip_newlines Removes any line breaks/newlines from a string. ✅ Yes
truncate Truncates a string down to the number of characters passed as the first parameter. An ellipsis (…) is appended to the truncated string and is included in the character count. ✅ Yes
truncatewords Truncates a string down to the number of words passed as the first parameter. An ellipsis (…) is appended to the truncated string. ✅ Yes
upcase Converts a string into uppercase. ✅ Yes

Additional Filters

The following general filters serve many different purposes, including formatting or converting content.

Filter Description Supported
date Converts a timestamp into another date format. Refer to Date Filter below for more. ✅ Yes
default Sets a default value for any variable with no assigned value. Can be used with strings, arrays, and hashes. ✅ Yes
format_address Formats an address to print the elements of the address in order according to their locale. ⛔ No
highlight Wraps words inside search results with an HTML <strong> tag with the class highlight if it matches the submitted search terms. ⛔ No
time_zone Refer to Time Zone Filter below for more. ✅ Yes

You can find more supported filters, such as encoding and URL filters, on our Advanced Filters page.

Date Filter

The date filter can be used to convert a timestamp into a different date format. You can pass in parameters to the date filter to reformat the timestamp. For examples of these parameters, refer to strfti.me.

For example, let’s say that the value of date_attribute is the timestamp 2021-06-03 17:13:41 UTC.

1
{{custom_attribute.${date_attribute} | date: '%b','d'}}
1
03 June

In addition to the strftime formatting options, Braze also supports converting a timestamp to Unix time with the %s date filter. For example, to get the date_attribute in Unix time:

1
{{custom_attribute.${date_attribute} | date: '%s' }}
1
1433351621

Time Zone Filter

In addition to the filters that you’ll find listed in Shopify’s documentation, Braze also supports the time_zone filter.

The time_zone filter takes a time, a time zone, and a date format and returns the time in that time zone in the specified date format. For example, let’s say that the value of {{custom_attribute.$date_attribute}}} is 2021-08-04 9:00:00 UTC:

1
{{custom_attribute.${date_attribute} | time_zone: 'America/Los_Angeles' | date: '%a %b %e %T' }}
1
Wed August 4 2:00:00

You can also use the reserved variable now to access the current date and time for manipulation.

1
{{ 'now' | date: '%Y-%m-%d %H:%M:%S' }}
1
2021-08-04 18:13:13
WAS THIS PAGE HELPFUL?
New Stuff!