Skip to main content
Skip table of contents

Filters

Filters are used when the output of a ZML object needs to be modified, be it in the case of text change, performing math functions, for encoding and decoding of strings, and more. They are used within an output and are separated by a | : {{object | filter}}. Additional information for each of the filters is listed below:

at_least

Filter = at_least

Limits a number to a minimum value.

INPUT

OUTPUT

{{ 4 | at_least: 5 }}

5

{{ 4 | at_least: 3 }}

4

currency

Filter = currency

Use the following Liquid filter for Currency Formatting:

CODE 
{{ money_value | currency:number_of_decimal_places, ‘language_country’ }}

Amount 

Code

$1,000.50 

CODE 
{{ 1000.5 | currency:2, ‘fr-CA’ }}

Below is a list of country/language combinations:

County/Language Combinations

  • af

  • ar

  • az

  • be

  • bg

  • bn

  • bs

  • ca

  • cs

  • cy

  • da

  • de

  • de-AT

  • de-CH

  • de-DE

  • el

  • el-CY

  • en

  • en-AU

  • en-CA

  • en-GB

  • en-IE

  • en-IN

  • en-NZ

  • en-US

  • en-ZA

  • en-CY

  • eo

  • es

  • es-419

  • es-AR

  • es-CL

  • es-CO

  • es-CR

  • es-EC

  • es-ES

  • es-MX

  • es-NI

  • es-PA

  • es-PE

  • es-US

  • es-VE

  • et

  • eu

  • fa

  • fi

  • fr

  • fr-CA

  • fr-CH

  • fr-FR

  • gl

  • he

  • hi

  • hi-IN

  • hr

  • hu

  • id

  • is

  • it

  • it-CH

  • ja

  • ka

  • km

  • kn

  • ko

  • lb

  • lo

  • lt

  • lv

  • mk

  • ml

  • mn

  • mr-IN

  • ms

  • nb

  • ne

  • nl

  • nn

  • oc

  • or

  • pa

  • pl

  • pt

  • pt-BR

  • rm

  • to

  • ru

  • sk

  • sl

  • sq

  • sr

  • sw

  • ta

  • th

  • tl

  • tr

  • tt

  • ug

  • ur

  • uz

  • vi

  • wo

  • zh-CN

  • zh-HK

  • zh-TW

  • zh-YUE

abs

Filter = abs

Returns the absolute value of a number:

INPUT

OUTPUT

{{ -17 | abs }}

17

INPUT

OUTPUT

{{ 4 | abs }}

4

abs will also work on a string that only contains a number:

INPUT

OUTPUT

{{ "-19.86" | abs }}

19.86

append

Filter = append

INPUT

OUTPUT

{{ "/my/fancy/url" | append: ".html" }}

/my/fancy/url.html

append can also be used with variables:

INPUT

OUTPUT

{% assign filename = "/index.html" %}

{{ "website.com" | append: filename }}

http://website.com/index.html

at_most

Filter = at_most

Limits a number to a maximum value.

INPUT

OUTPUT

{{ 4 | at_most: 5 }}

4

INPUT

OUTPUT

{{ 4 | at_most: 3 }}

3

capitalize

Filter = capitalize

Makes the first character of a string capitalized.

INPUT

OUTPUT

{{ "title" | capitalize }}

Title

Capitalize only capitalizes the first character of a string, so later words are not affected:

INPUT

OUTPUT

{{ "my great title" | capitalize }}

My great title

ceil

Filter = ceil

Rounds the input up to the nearest whole number. Liquid tries to convert the input to a number before the filter is applied:

INPUT

OUTPUT

{{ 1.2 | ceil }}

2

INPUT

OUTPUT

{{ 2.0 | ceil }}

2

INPUT

OUTPUT

{{ 183.357 | ceil }}

184

Here the input value is a string:

INPUT

OUTPUT

{{ "3.5" | ceil }}

4

compact

Filter= compact

Removes any nil values from an array.

For this example, assume site.pages is an array of content pages for a website, and some of these pages have an attribute called category that specifies their content category. If we map those categories to an array, some of the array items might be nil if any pages do not have a category attribute.

INPUT

OUTPUT

{% assign site_categories = site.pages | map: "category" %} {% for category in site_categories %} - {{ category }} {% endfor %}

  • business

  • celebrities

  • lifestyle

  • sports

  • technology

By using compact when we create our site_categories array, we can remove all the nil values in the array.

INPUT

OUTPUT

{% assign site_categories = site.pages | map: "category" | compact %} {% for category in site_categories %} - {{ category }} {% endfor %}

  • business

  • celebrities

  • lifestyle

  • sports

  • technology

concat

Filter= concat

Concatenates (joins together) multiple arrays. The resulting array contains all the items from the input arrays:

INPUT

OUTPUT

{% assign fruits = "apples, oranges, peaches" | split: ", " %} {% assign vegetables = "carrots, turnips, potatoes" | split: ", " %} {% assign everything = fruits | concat: vegetables %} {% for item in everything %} - {{ item }} {% endfor %}

  • apples

  • oranges

  • peaches

  • carrots

  • turnips

  • potatoes

You can string together concat filters to join more than two arrays:

INPUT

OUTPUT

{% assign furniture = "chairs, tables, shelves" | split: ", " %} {% assign everything = fruits | concat: vegetables | concat: furniture %} {% for item in everything %} - {{ item }} {% endfor %}

  • apples

  • oranges

  • peaches

  • carrots

  • turnips

  • potatoes

  • chairs

  • tables

  • shelves

date

Filter = date

Converts a timestamp into another date format. The format for this syntax is the same as strftime. The input uses the same format as Ruby’s Time.parse.

INPUT

OUTPUT

{{ article.published_at | date: "%a, %b %d, %y" }}

Fri, Jul 17, 15

INPUT

OUTPUT

{{ article.published_at | date: "%Y" }}

2015

date works on strings if they contain well-formatted dates:

INPUT

OUTPUT

{{ "March 14, 2016" | date: "%b %d, %y" }}

Mar 14, 16

To get the current time, pass the special word "now" (or "today") to date:

INPUT

OUTPUT

This page was last updated at {{ "now" | date: "%Y-%m-%d %H:%M" }}.

This page was last updated at 2019-09-19 17:48.

The value will be the current time of when the page was last generated from the template, not when the page is presented to a user if caching or static site generation is involved.

default

Filter = default

Allows you to specify a fallback in case a value doesn’t exist. default will show its value if the left side is nil, false, or empty. In this example, product_price is not defined, so the default value is used.

INPUT

OUTPUT

{{ product_price | default: 2.99 }}

2.99

In this example, product_price is defined, so the default value is not used.

INPUT

OUTPUT

{% assign product_price = 4.99 %} {{ product_price | default: 2.99 }}

4.99

In this example, product_price is empty, so the default value is used.

INPUT

OUTPUT

{% assign product_price = "" %} {{ product_price | default: 2.99 }}

2.99

divided_by

Filter = divided_by

Divides a number by another number. The result is rounded down to the nearest integer (that is, the floor) if the divisor is an integer.

INPUT

OUTPUT

{{ 16 | divided_by: 4 }}

4

INPUT

OUTPUT

{{ 5 | divided_by: 3 }}

1

Controlling Rounding

divided_by produces a result of the same type as the divisor — that is, if you divide by an integer, the result will be an integer. If you divide by a float (a number with a decimal in it), the result will be a float. For example, here the divisor is an integer:

INPUT

OUTPUT

{{ 20 | divided_by: 7 }}

2

Here it is a float:

INPUT

OUTPUT

{{ 20 | divided_by: 7.0 }}

2.857142857142857

Changing Variable Types

You might want to use a variable as a divisor, in which case you can’t simply add .0 to convert it to a float. In these cases, you can assign a version of your variable converted to a float using the times filter. In this example, we’re dividing by a variable that contains an integer, so we get an integer:

INPUT

OUTPUT

{% assign my_integer = 7 %} {{ 20 | divided_by: my_integer }}

2

Here, we multiply the variable by 1.0 to get afloat, then divide by the float instead:

INPUT

OUTPUT

{% assign my_integer = 7 %} {% assign my_float = my_integer | times: 1.0 %} {{ 20 | divided_by: my_float }}

2.857142857142857

downcase

Filter = downcase

Makes each character in a string lowercase. It has no effect on strings that are already all lowercase.

INPUT

OUTPUT

{{ "Parker Moore" | downcase }}

parker moore

INPUT

OUTPUT

{{ "apple" | downcase }}

apple

escape

Filter = escape

Escapes a string by replacing characters with escape sequences (so that the string can be used in a URL, for example). It doesn’t change strings that don’t have anything to escape.

INPUT

OUTPUT

{ "Have you read 'James & the Giant Peach'?" | escape }}

Have you read 'James & the Giant Peach'?

INPUT

OUTPUT

{{ "Tetsuro Takara" | escape }}

Tetsuro Takara

escape_once

Filter = escape_once

Escapes a string without changing existing escaped entities. It doesn’t change strings that don’t have anything to escape.

INPUT

OUTPUT

{{ "1 < 2 & 3" | escape_once }}

1 &lt; 2 &amp; 3

INPUT

OUTPUT

{{ "1 &lt; 2 &amp; 3" | escape_once }}

1 &lt; 2 &amp; 3

first

Filter = first

Returns the first item of an array.

INPUT

OUTPUT

{{ "Ground control to Major Tom." | split: " " | first }}

Ground

INPUT

OUTPUT

{% assign my_array = "zebra, octopus, giraffe, tiger" | split: ", " %} {{ my_array.first }}

zebra

You can use "first" with dot notation when you need to use the filter inside a tag:

Example

{% if my_array.first == "zebra" %} Here comes a zebra! {% endif %}

floor

Filter = floor

Rounds the input down to the nearest whole number. Liquid tries to convert the input to a number before the filter is applied.

INPUT

OUTPUT

{{ 1.2 | floor }}

1

INPUT

OUTPUT

{{ 2.0 | floor }}

2

INPUT

OUTPUT

{{ 183.357 | floor }}

183

 Here the input value is a string:

INPUT

OUTPUT

{{ "3.5" | floor }}

3

join

Filter = join

Combines the items in an array into a single string using the argument as a separator.

INPUT

OUTPUT

{% assign beatles = "John, Paul, George, Ringo" | split: ", " %} {{ beatles | join: " and " }}

John and Paul and George and Ringo

last

Filters = last

Returns the last item of an array.

INPUT

OUTPUT

{{ "Ground control to Major Tom." | split: " " | last }}

Tom

INPUT

OUTPUT

{% assign my_array = "zebra, octopus, giraffe, tiger" | split: ", " %} {{ my_array.last }}

tiger

You can use "last" with dot notation when you need to use the filter inside a tag:

Example

{% if my_array.last == "tiger" %} There goes a tiger! {% endif %}

lstrip

Filter = lstrip

Removes all whitespace (tabs, spaces, and newlines) from the left side of a string. It does not affect spaces between words.

INPUT

OUTPUT

{{ " So much room for activities! " | lstrip }}

So much room for activities!

map

Filters = map

It creates an array of values by extracting the values of a named property from another object. In this example, assume the object site.pages contain all the metadata for a website. Using assign with the map filter creates a variable that contains only the values of the category properties of everything on the site.pages object.

INPUT

OUTPUT

{% assign all_categories = site.pages | map: "category" %} {% for item in all_categories %} - {{ item }} {% endfor %}

  • business

  • celebrities

  • lifestyle

  • sports

  • technology

minus

Filter= minus

Subtracts a number from another number.

INPUT

OUTPUT

{{ 4 | minus: 2 }}

2

INPUT

OUTPUT

{{ 16 | minus: 4 }}

12

INPUT

OUTPUT

{{ 183.357 | minus: 12 }}

171.357

modulo

Filter = modulo

Returns the remainder of a division operation.

INPUT

OUTPUT

{{ 3 | modulo: 2 }}

1

INPUT

OUTPUT

{{ 24 | modulo: 7 }}

3

INPUT

OUTPUT

{{ 183.357 | modulo: 12 }}

3.357

newline_to_br

Filter = newline_to_br

Replaces every newline (\n) in a string with an HTML line break (<br />).

INPUT

OUTPUT

{% capture string_with_newlines %} Hello there {% endcapture %} {{ string_with_newlines | newline_to_br }}

<br /> Hello<br /> there<br />

plus

Filter = plus

Adds a number to another number.

INPUT

OUTPUT

{{ 4 | plus: 2 }}

6

INPUT

OUTPUT

{{ 16 | plus: 4 }}

20

INPUT

OUTPUT

{{ 183.357 | plus: 12 }}

195.357

prepend

Filter= prepend

Adds the specified string to the beginning of another string.

INPUT

OUTPUT

{{ "apples, oranges, and bananas" | prepend: "Some fruit: " }}

Some fruit: apples, oranges, and bananas

"prepend" can also be used with variables:

INPUT

OUTPUT

{% assign url = "example.com" %} {{ "/index.html" | prepend: url }}

example.com/index.html

remove

Filter = remove

Removes every occurrence of the specified substring from a string.

INPUT

OUTPUT

{{ "I strained to see the train through the rain" | remove: "rain" }}

I sted to see the t through the

remove_first

Filter = remove_first

Removes only the first occurrence of the specified substring from a string.

INPUT

OUTPUT

{{ "I strained to see the train through the rain" | remove_first: "rain" }}

I sted to see the train through the rain

replace

Filter = replace

Replaces every occurrence of the first argument is a string with the second argument.

INPUT

OUTPUT

{{ "Take my protein pills and put my helmet on" | replace: "my", "your" }}

Take your protein pills and put your helmet on

replace_first

Filter = replace_first

Replaces only the first occurrence of the first argument is a string with the second argument.

INPUT

OUTPUT

{{ "Take my protein pills and put my helmet on" | replace_first: "my", "your" }}

Take your protein pills and put my helmet on

reverse

Filter = reverse

Reverses the order of the items in an array. reverse cannot reverse a string.

INPUT

OUTPUT

{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %} {{ my_array | reverse | join: ", " }}

plums, peaches, oranges, apples

Although reverse cannot be used directly on a string, you can split a string into an array, reverse the array, and rejoin it by chaining together filters:

INPUT

OUTPUT

{{ "Ground control to Major Tom." | split: "" | reverse | join: "" }}

.moT rojaM ot lortnoc dnuorG

round

Filter = round

Rounds a number to the nearest integer or, if a number is passed as an argument, to that number of decimal places.

INPUT

OUTPUT

{{ 1.2 | round }}

1

INPUT

OUTPUT

{{ 2.7 | round }}

3

INPUT

OUTPUT

{{ 183.357 | round: 2 }}

183.36

rstrip

Filter= rstrip

Removes all whitespace (tabs, spaces, and newlines) from the right side of a string. It does not affect spaces between words.

INPUT

OUTPUT

{{ " So much room for activities! " | rstrip }}

So much room for activities!

size

Filter = size

Returns the number of characters in a string or the number of items in an array.

INPUT

OUTPUT

{{ "Ground control to Major Tom." | size }}

28

INPUT

OUTPUT

{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %} {{ my_array.size }}

4

You can use "size" with dot notation when you need to use the filter inside a tag:

Example

{% if site.pages.size > 10 %} This is a big website! {% endif %}

slice

Filter = slice

Returns a substring of 1 character beginning at the index specified by the first argument. An optional second argument specifies the length of the substring to be returned.

String indices are numbered starting from 0.

INPUT

OUTPUT

{{ "Liquid" | slice: 0 }}

L

INPUT

OUTPUT

{{ "Liquid" | slice: 2 }}

q

INPUT

OUTPUT

{{ "Liquid" | slice: 2, 5 }}

quid

 If the first argument is a negative number, the indices are counted from the end of the string:

INPUT

OUTPUT

{{ "Liquid" | slice: -3, 2 }}

ui

sort

Filter = sort

Sorts items in an array in case-sensitive order.

INPUT

OUTPUT

{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " %} {{ my_array | sort | join: ", " }}

Sally Snake, giraffe, octopus, zebra

An optional argument specifies which property of the array’s items to use for sorting.

Example

{% assign products_by_price = collection.products | sort: "price" %} {% for product in products_by_price %} <h4>{{ product.title }}</h4> {% endfor %}

sort_natural

Filter = sort_natural

Sorts items in an array in case-sensitive order.

INPUT

OUTPUT

{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " %} {{ my_array | sort | join: ", " }}

Sally Snake, giraffe, octopus, zebra

An optional argument specifies which property of the array’s items to use for sorting.

Example

{% assign products_by_price = collection.products | sort: "price" %} {% for product in products_by_price %} <h4>{{ product.title }}</h4> {% endfor %}

split

Filter = split

Divides a string into an array using the argument as a separator. "split" is commonly used to convert comma-separated items from a string to an array.

INPUT

OUTPUT

{% assign beatles = "John, Paul, George, Ringo" | split: ", " %} {% for member in beatles %} {{ member }} {% endfor %}

  • John

  • Paul

  • George

  • Ringo

strip

Filter = strip

Removes all whitespace (tabs, spaces, and newlines) from both the left and right sides of a string. It does not affect spaces between words.

INPUT

OUTPUT

{{ " So much room for activities! " | strip }}

So much room for activities!

strip_html

Filter = strip_html

Removes any HTML tags from a string.

INPUT

OUTPUT

{{ "Have <em>you</em> read <strong>Ulysses</strong>?" | strip_html }}

Have you read Ulysses?

strip_newlines

Filter = strip_newlines

Removes any newline characters (line breaks) from a string.

INPUT

OUTPUT

{% capture string_with_newlines %} Hello there {% endcapture %} {{ string_with_newlines | strip_newlines }}

Hellothere

times

Filter = times

Multiplies a number by another number.

INPUT

OUTPUT

{{ 3 | times: 2 }}

6

INPUT

OUTPUT

{{ 24 | times: 7 }}

168

INPUT

OUTPUT

{{ 183.357 | times: 12 }}

2200.284

title_case

Filter = title_case

Converts strings to title case.

INPUT

OUTPUT

{{ "my great title" | title_case }}

My Great Title

truncate

Filter = truncate

Shortens a string down to the number of characters passed as an argument. If the specified number of characters is less than the length of the string, an ellipsis (…) is appended to the string and is included in the character count.

INPUT

OUTPUT

{{ "Ground control to Major Tom." | truncate: 20 }}

Ground control to...

Custom Ellipsis

"truncate" takes an optional second argument that specifies the sequence of characters to be appended to the truncated string. By default, this is an ellipsis (…), but you can specify a different sequence.

The length of the second argument counts against the number of characters specified by the first argument. For example, if you want to truncate a string to exactly 10 characters, and use a 3-character ellipsis, use 13 for the first argument of truncate, since the ellipsis counts as 3 characters.

INPUT

OUTPUT

{{ "Ground control to Major Tom." | truncate: 25, ", and so on" }}

Ground control, and so on

No Ellipsis

You can truncate to the exact number of characters specified by the first argument and avoid showing trailing characters by passing a blank string as the second argument:

INPUT

OUTPUT

{{ "Ground control to Major Tom." | truncate: 20, "" }}

Ground control to Ma

truncatewords

Filter = truncatewords

Shortens a string down to the number of words passed as an argument. If the specified number of words is less than the number of words in the string, an ellipsis (…) is appended to the string.

INPUT

OUTPUT

{{ "Ground control to Major Tom." | truncatewords: 3 }}

Ground control to...

Custom Ellipsis

"truncatewords" takes an optional second argument that specifies the sequence of characters to be appended to the truncated string. By default, this is an ellipsis (…), but you can specify a different sequence.

INPUT

OUTPUT

{{ "Ground control to Major Tom." | truncatewords: 3, "--" }}

Ground control to--

No Ellipsis

You can avoid showing trailing characters by passing a blank string as the second argument:

INPUT

OUTPUT

{{ "Ground control to Major Tom." | truncatewords: 3, "" }}

Ground control to

uniq

Filter = uniq

Removes any duplicate elements in an array.

INPUT

OUTPUT

{% assign my_array = "ants, bugs, bees, bugs, ants" | split: ", " %} {{ my_array | uniq | join: ", " }}

ants, bugs, bees

upcase

Filter = upcase

Makes each character in a string uppercase. It has no effect on strings that are already all uppercase.

INPUT

OUTPUT

{{ "Parker Moore" | upcase }}

PARKER MOORE

INPUT

OUTPUT

{{ "APPLE" | upcase }}

APPLE

url_decode

Filters = url_decode

Decodes a string that has been encoded as a URL or by url_encode.

INPUT

OUTPUT

{{ "%27Stop%21%27+said+Fred" | url_decode }}

'Stop!' said Fred

url_encode

Filter = url_encode

Converts any URL-unsafe characters in a string into percent-encoded characters.

INPUT

OUTPUT

{{ "john@liquid.com" | url_encode }}

john%40liquid.com

INPUT

OUTPUT

{{ "Tetsuro Takara" | url_encode }}

Tetsuro+Takara

where

Filter = where

Creates an array including only the objects with a given property value, or any truthy value by default. In this example, assume you have a list of products and you want to show your kitchen products separately. Using where, you can create an array containing only the products that have a type of kitchen.

INPUT

OUTPUT

All products: {% for product in products %} - {{ product.title }} {% endfor %} {% assign kitchen_products = products | where: "type", "kitchen" %} Kitchen products: {% for product in kitchen_products %} - {{ product.title }} {% endfor %}

All Products:

  • Vacuum

  • Spatula

  • Television

  • Garlic press

Kitchen Products:

  • Spatula

  • Garlic press

Say instead you have a list of products and you only want to show those that are available to buy. You can use where with a property name but no target value to include all products with a truthy "available" value.

INPUT

OUTPUT

All products:

{% for product in products %}

  • {{ product.title }}

{% endfor %}

{% assign available_products = products | where: "available" %}

Available products:

{% for product in available_products %}

  • {{ product.title }}

{% endfor %}

All Products:

  • Coffee mug

  • Limited edition sneakers

  • Boring sneakers

Available Products:

  • Coffee mug

  • Boring sneakers

The where filter can also be used to find a single object in an array when combined with the "first" filter. For example, say you want to show off the shirt in your new fall collection.

INPUT

OUTPUT

{% assign new_shirt = products | where: "type", "shirt" | first %} Featured product: {{ new_shirt.title }}

Featured Product: Hawaiian print sweater vest

encrypt/decrypt

Filter = encrypt or decrypt

The Zeta Marketing Platform offers two types of encryption and decryption methods, AES and DES.

AES

encrypt

{{ data | encrypt: 'AES'}}

decrypt

{{ data | decrypt: 'AES'}}

DES

encrypt

{{ data | encrypt: 'DES','key','mode','iv','padding' }}

decrypt

{{ data | decrypt: 'DES','key','mode','iv','padding' }}

sha256

Filter = sha256

Creates a SHA256 hash of the data. This is a one-way function and cannot be reversed.

Example

{{ data | sha256 }}

base64_encode

Filter = base64_encode

Encodes data as a base64 string. Can be decoded using the base64_decode filter.

Example

{{data | base64_encode}}

base64_decode

Filter = base64_decode

Used to decode base64 encoded data.

Example Usage

{{ data | base64_decode }}

ascii_to_hex

hex_to_ascii

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close