Filters are simple methods that modify the output of numbers, strings, variables and objects. They are placed within an output tag {{
}}
and are denoted by a pipe character |
.
Input<!-- item.title = "Invisible Watch" -->{{ item.title | upcase }}
OutputINVISIBLE WATCH
In the example above, item
is the object, title
is its attribute, and upcase
is the filter being applied.
Some filters require a parameter to be passed.
Input{{ item.title | remove: "Invisible" }}
OutputWatch
Multiple filters can be used on one output. They are applied from left to right.
Input<!-- item.title = "Invisible Watch" -->{{ item.title | upcase | remove: "INVISIBLE" }}
OutputWATCH
Array filters change the output of arrays. Array is a synonym to list. For example, order.line_items
is an array of line items or order.transactions
is an array of transactions.
Joins the elements of an array with the character passed as the parameter. The result is a single string.
Input{{ product.tags | join: ', ' }}
Outputtag1, tag2, tag3
Returns the first element of an array.
Input<!-- product.tags = "sale", "mens", "womens", "awesome" -->{{ product.tags | first }}
Outputsale
You can use first
with dot notation when you need to use the filter inside a tag.
{% if product.tags.first == "sale" %}This product is on sale!{% endif %}
Returns the last element of an array.
Input<!-- product.tags = "sale", "mens", "womens", "awesome" -->{{ product.tags | last }}
Outputawesome
You can use last
with dot notation when you need to use the filter inside a tag.
{% if product.tags.last == "sale"%}This product is on sale!{% endif %}
Using last
on a string returns the last character in the string.
Input<!-- product.title = "Awesome Shoes" -->{{ product.title | last }}
Outputs
Concatenates (combines) an array with another array. The resulting array contains all the elements of the original arrays. concat
will not remove duplicate entries from the concatenated array unless you also use the uniq
filter.
Input{% assign fruits = "apples, oranges, peaches, tomatoes" | split: ", " %}{% assign vegetables = "broccoli, carrots, lettuce, tomatoes" | split: ", " %}{% assign plants = fruits | concat: vegetables %}{{ plants | join: ", " }}
Outputapples, oranges, peaches, tomatoes, broccoli, carrots, lettuce, tomatoes
You can string together multiple concat
filters to combine more than two arrays:
Input{% assign fruits = "apples, oranges, peaches" | split: ", " %}{% assign vegetables = "broccoli, carrots, lettuce" | split: ", " %}{% assign animals = "dogs, cats, birds" | split: ", " %}{% assign things = fruits | concat: vegetables | concat: animals %}{{ things | join: ", " }}
Outputapples, oranges, peaches, broccoli, carrots, lettuce, dogs, cats, birds
Returns the item at the specified index location in an array. Note that array numbering starts from zero, so the first item in an array is referenced with [0]
.
Input<!-- product.tags = "sale", "mens", "womens", "awesome" -->{{ product.tags[2] }}
Outputwomens
Accepts an array element's attribute as a parameter and creates an array out of each array element's value.
Input<!-- collection.title = "Spring", "Summer", "Fall", "Winter" -->{% assign collection_titles = collections | map: 'title' %}{{ collection_titles }}
OutputSpringSummerFallWinter
Reverses the order of the items in an array.
Input{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}{{ my_array | reverse | join: ", " }}
Outputplums, peaches, oranges, apples
Returns the size of a string (the number of characters) or an array (the number of elements).
Input{{ 'The quick brown fox jumps over a lazy dog.' | size }}
Output42
You can use size
with dot notation when you need to use the filter inside a tag.
{% if collections.frontpage.products.size > 10 %}There are more than 10 products in this collection!{% endif %}
Sorts the elements of an array by a given attribute of an element in the array.
{% assign products = collection.products | sort: 'price' %}{% for product in products %}<h4>{{ product.title }}</h4>{% endfor %}
The order of the sorted array is case-sensitive.
Input<!-- products = "a", "b", "A", "B" -->{% assign products = collection.products | sort: 'title' %}{% for product in products %}{{ product.title }}{% endfor %}
OutputA B a b
Creates an array including only the objects with a given property value, or any truthy value by default.
InputAll products:{% for product in collection.products %}- {{ product.title }}{% endfor %}{% assign kitchen_products = collection.products | where: "type", "kitchen" %}Kitchen products:{% for product in kitchen_products %}- {{ product.title }}{% endfor %}
OutputAll products:- Vacuum- Spatula- Television- Garlic pressKitchen products:- Spatula- Garlic press
You can use a property name with where
that has no target value when that property is a boolean or truthy. For example, the available
property of products.
Example
{% assign available_products = collection.products | where: "available" %}Available products:{% for product in available_products %}- {{ product.title }}{% endfor %}
Removes any duplicate instances of elements in an array.
Input{% assign fruits = "orange apple banana apple orange" %}{{ fruits | split: ' ' | uniq | join: ' ' }}
Outputorange apple banana
Converts a timestamp into a specified date format.
format | description | example value |
%d | Two-digit day of the month (with leading zeros) | |
%m | Two digit representation of the month | |
%y | Two digit representation of the year |
|
%Y | Four digit representation for the year |
|
%H | Two digit representation of the hour in 24-hour format |
|
%I | Two digit representation of the hour in 12-hour format |
|
%p | Upper-case 'AM' or 'PM' based on the given time |
|
%P | Lower-case 'am' or 'pm' based on the given time |
|
%M | Two digit representation of the minute |
|
%S | Two digit representation of the second |
|
%s | Unix Epoch Time timestamp |
|
Input{{ order.created_at | date: "%Y-%m-%d %H:%M:%S" }}
Output2021-02-03 04:56:07
Math filters allow you to apply mathematical tasks.
Math filters can be linked and, as with any other filters, are applied in order of left to right. In the example below, minus
is applied first, then times
, and finally divided_by
.Copy
You save {{ product.compare_at_price | minus: product.price | times: 100.0 | divided_by: product.compare_at_price }}%
Returns the absolute value of a number.
Input{{ -25 | abs }}
Output25
abs
will also work on a string if the string only contains a number.
Input{{ "-19.86" | abs }}
Output19.86
Limits a number to a maximum value.
Input{{ 4 | at_most: 5 }}{{ 4 | at_most: 3 }}
Output43
Limits a number to a minimum value.
Input{{ 4 | at_least: 5 }}{{ 4 | at_least: 3 }}
Output54
Rounds an output up to the nearest integer.
Input{{ 1.2 | ceil }}{{ 3.0 | ceil }}{{ 3.45 | ceil }}
Output234
Liquid tries to convert the input to a number before the filter is applied.
Input{{ "4.5" | ceil }}
Output5
Divides an output by a number. The output is rounded down to the nearest integer.
Input<!-- product.price = 200 -->{{ product.price | divided_by: 10 }}
Output20
Rounds an output down to the nearest integer.
Input{{ 4.6 | floor }}{{ 4.3 | floor }}
Output44
Subtracts a number from an output.
Input<!-- product.price = 200 -->{{ product.price | minus: 15 }}
Output185
Divides an output by a number and returns the remainder.
Input{{ 12 | modulo: 5 }}
Output2
Adds a number to an output.
Input<!-- product.price = 200 -->{{ product.price | plus: 15 }}
Output215
Rounds the output to the nearest integer or specified number of decimals.
Input{{ 4.6 | round }}{{ 4.3 | round }}{{ 4.5612 | round: 2 }}
Output544.56
Multiplies an output by a number.
Input<!-- product.price = 200 -->{{ product.price | times: 1.15 }}
Output230
Convert a number into a string, rounding the number to keep only the given number of decimals. The difference between round and to_fixed it that the latter will
Input{{ 1.2345 | to_fixed: 2 }}
Output1.23
The difference between round
and to_fixed
it that round
returns a number so it trims trailing zeros while to_fixed
will preserve them.
Input{{ 4.5000 | round: 2 }}{{ 4.5000 | to_fixed: 2 }}
Output4.54.50
String filters are used to manipulate outputs and variables of the string type.
Appends characters to a string.
Input{% assign filename = "/index.html" %}{{ "website.com" | append: filename }}
Outputwebsite.com/index.html
Capitalizes the first word in a string
Input{{ "title" | capitalize }}
OutputTitle
Converts a string into lowercase.
Input{{ 'UPPERCASE' | downcase }}
Outputuppercase
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{{ "<p>test</p>" | escape }}
Output<p>test</p>
Inserts a <br > linebreak HTML tag in front of each line break in a string.
Input{% capture var %}OneTwoThree{% endcapture %}{{ var | newline_to_br }}
Output<br />One<br />Two<br />Three<br />
Adds the specified string to the beginning of another string.
Input{{ 'sale' | prepend: 'Made a great ' }}
OutputMade a great sale
Removes all occurrences of a substring from a string.
Input{{ "Hello, world. Goodbye, world." | remove: "world" }}
OutputHello, . Goodbye, .
Removes only the first occurrence of a substring from a string.
Input{{ "Hello, world. Goodbye, world." | remove_first: "world" }}
OutputHello, . Goodbye, world.
Replaces all occurrences of a string with a substring.
Input<!-- product.title = "Awesome Shoes" -->{{ product.title | replace: 'Awesome', 'Mega' }}
OutputMega Shoes
Replaces the first occurrence of a string with a substring.
Input<!-- product.title = "Awesome Awesome Shoes" -->{{ product.title | replace_first: 'Awesome', 'Mega' }}
OutputMega Awesome Shoes
The slice
filter returns a substring, starting at the specified index. An optional second parameter can be passed to specify the length of the substring. If no second parameter is given, a substring of one character will be returned.
Input{{ "hello" | slice: 0 }}{{ "hello" | slice: 1 }}{{ "hello" | slice: 1, 3 }}
Outputheell
If the passed index is negative, it is counted from the end of the string.
Input{{ "hello" | slice: -3, 2 }}
Outputll
The split
filter takes on a substring as a parameter. The substring is used as a delimiter to divide a string into an array. You can output different parts of an array using array filters.
Input{% assign words = "Hi, how are you today?" | split: ' ' %}{%- for word in words -%}{{ word }}{% endfor %}
OutputHi,howareyoutoday?
Strips tabs, spaces, and newlines (all whitespace) from the left and right side of a string.
Input{{ ' too many spaces ' | strip }}
Outputtoo many spaces
Strips tabs, spaces, and newlines (all whitespace) from the left side of a string.
Input{{ ' too many spaces ' | lstrip }}!
Outputtoo many spaces !
Strips tabs, spaces, and newlines (all whitespace) from the right side of a string.
Input{{ ' too many spaces ' | rstrip }}!
Outputtoo many spaces!
Strips all HTML tags from a string.
Input{{ "<h1>Hello</h1> World" | strip_html }}
OutputHello World
Removes any line breaks/newlines from a string.
Input{%- capture string_with_newlines -%}Hellothere{%- endcapture -%}{{ string_with_newlines | strip_newlines }}
OutputHellothere
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.
Input{{ "The cat came back the very next day" | truncate: 13 }}
OutputThe cat ca...
truncate
takes an optional second parameter 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 parameter counts against the number of characters specified by the first parameter. For example, if you want to truncate a string to exactly 10 characters, and use a 3-character ellipsis, use 13 for the first parameter of truncate
, since the ellipsis counts as 3 characters.
Input{{ "ABCDEFGHIJKLMNOPQRSTUVWXYZ" | truncate: 18, ", and so on" }}
OutputABCDEFG, and so on
You can truncate to the exact number of characters specified by the first parameter and show no trailing characters by passing a blank string as the second parameter:
Input{{ "I'm a little teapot, short and stout." | truncate: 15, "" }}
OutputI'm a little te
Truncates a string down to the number of words passed as the first parameter. An ellipsis (...) is appended to the truncated string.
Input{{ "The cat came back the very next day" | truncatewords: 4 }}
OutputThe cat came back...
truncatewords
takes an optional second parameter 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{{ "The cat came back the very next day" | truncatewords: 4, "--" }}
OutputThe cat came back--
You can avoid showing trailing characters by passing a blank string as the second parameter:
Input{{ "The cat came back the very next day" | truncatewords: 4, "" }}
OutputThe cat came back
Converts a string into uppercase.
Input{{ 'i want this to be uppercase' | upcase }}
OutputI WANT THIS TO BE UPPERCASE
Decodes a string that has been encoded as a URL or by url_encode.
Input{{ "%27Stop%21%27+said+Fred" | url_decode }}
Output'Stop!' said Fred
Converts any URL-unsafe characters in a string into percent-encoded characters.
Input{{ "john@liquid.com" | url_encode }}
john%40liquid.com
Note that url_encode
will turn a space into a +
sign instead of a percent-encoded character.
Input{{ "Tetsuro Takara" | url_encode }}
OutputTetsuro+Takara
This is a special filter available in Exporteo to facilitate the setup of an XML output template.
Replaces characters that are special characters in XML documents.
Char | Escape String |
< | < |
> | > |
" | " |
' | ' |
& | & |
Input{{ "Jane & Joe O'Neill" | xml_escape }}
OutputJane & Joe O'Neill