Liquid - Filters
abs
Returns the absolute value of a number.
Input
{{ -17 | abs }}
Output
17
Input
{{ 4 | abs }}
Output
4
abs will also work on a string if the string only contains a number.
Input
{{ "-19.86" | abs }}
Output
19.86
append
Concatenates two strings and returns the concatenated value.
Input
{{ "/my/fancy/url" | append: ".html" }}
Output
hello.html
append can also be used with variables:
Input
{% assign filename = "/index.html" %}
{{ "website.com" | append: filename }}
Output
website.com/index.html
append can be used with a number, it will return a string:
Input
{{ 3 | append: ' stooges' }}
Output
3 stooges
at_least
Limits a number to a minimum value.
Input
{{ 4 | at_least: 5 }}
Output
5
Input
{{ 4 | at_least: 3 }}
Output
4
at_most
Limits a number to a maximum value.
Input
{{ 4 | at_most: 5 }}
Output
4
Input
{{ 4 | at_most: 3 }}
Output
3
capitalize
Makes the first character of a string capitalized.
Input
{{ "title" | capitalize }}
Output
Title
capitalize only capitalizes the first character of the string, so later words are not affected:
Input
{{ "my great title" | capitalize }}
Output
My great title
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
{{ 1.2 | ceil }}
Output
2
Input
{{ 2.0 | ceil }}
Output
2
Input
{{ 183.357 | ceil }}
Output
184
Here the input value is a string:
Input
{{ "3.5" | ceil }}
Output
4
concat
Concatenates (joins together) multiple arrays. The resulting array contains all the items from the input arrays.
Input
{% assign fruits = "apples, oranges, peaches" | split: ", " %}
{% assign vegetables = "carrots, turnips, potatoes" | split: ", " %}
{% assign everything = fruits | concat: vegetables %}
{% for item in everything %}
- {{ item }}
{% endfor %}
Output
- apples
- oranges
- peaches
- carrots
- turnips
- potatoes
You can string together concat filters to join more than two arrays:
Input
{% assign furniture = "chairs, tables, shelves" | split: ", " %}
{% assign everything = fruits | concat: vegetables | concat: furniture %}
{% for item in everything %}
- {{ item }}
{% endfor %}
Output
- apples
- oranges
- peaches
- carrots
- turnips
- potatoes
- chairs
- tables
- shelves
date
Converts a timestamp into another date format. The format for this syntax is the same as strftime. You can use the standard date formatting for UNIX. Available directives for time and date are listed here.
Input
{{ article.published_at | date: "%a, %b %d, %y" }}
Output
Fri, Jul 17, 15
Input
{{ article.published_at | date: "%Y" }}
Output
2015
date works on strings if they contain well-formatted dates:
Input
{{ "March 14, 2016" | date: "%b %d, %y" }}
Output
Mar 14, 16
To get the current time, pass the special word "now" (or "today") to date:
Input
This page was last updated at {{ "now" | date: "%Y-%m-%d %H:%M" }}.
Output
This page was last updated at 2024-11-05 11:43.
Note that 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
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
{{ product_price | default: 2.99 }}
Output
2.99
In this example, product_price is defined, so the default value is not used.
Input
{% assign product_price = 4.99 %}
{{ product_price | default: 2.99 }}
Output
4.99
In this example, product_price is empty, so the default value is used.
Input
{% assign product_price = "" %}
{{ product_price | default: 2.99 }}
Output
2.99
To allow variables to return false instead of the default value, you can use the allow_false parameter.
Input
{{ settings.flag | default: true, allow_false: true }}
Output
<!-- If settings.flag is false -->
false
divided_by
Divides a number by the specified number.
The result is rounded down to the nearest integer (that is, the floor) if the divisor is an integer.
Input
{{ 16 | divided_by: 4 }}
Output
4
Input
{{ 5 | divided_by: 3 }}
Output
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
{{ 20 | divided_by: 7 }}
Output
2
Here it is a float:
Input
{{ 20 | divided_by: 7.0 }}
Output
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, you’re dividing by a variable that contains an integer, so you get an integer:
Input
{% assign my_integer = 7 %}
{{ 20 | divided_by: my_integer }}
Output
2
Here, you multiply the variable by 1.0 to get a float, then divide by the float instead:
Input
{% assign my_integer = 7 %}
{% assign my_float = my_integer | times: 1.0 %}
{{ 20 | divided_by: my_float }}
Output
2.857142857142857
downcase
Makes each character in a string lowercase. It has no effect on strings which are already all lowercase.
Input
{{ "Parker Moore" | downcase }}
Output
parker moore
Input
{{ "apple" | downcase }}
Output
apple
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
{{ "Have you read 'James & the Giant Peach'?" | escape }}
Output
Have you read 'James & the Giant Peach'?
Input
{{ "Nikola Tesla" | escape }}
Output
Nikola Tesla
## first Returns the first item of an array. #### Input ```liquid {% assign my_array = "apples, oranges, peaches, plums" | split: ", " %} {{ my_array.first }}
Output
apples
Input
{% assign my_array = "zebra, octopus, giraffe, tiger" | split: ", " %}
{{ my_array.first }}
Output
zebra
floor
Rounds a number down to the nearest whole number. Liquid tries to convert the input to a number before the filter is applied.
Input
{{ 1.2 | floor }}
Output
1
Input
{{ 2.0 | floor }}
Output
2
Input
{{ 183.357 | floor }}
Output
183
Here the input value is a string:
Input
{{ "3.5" | floor }}
Output
3
join
Combines the items in an array into a single string using the argument as a separator.
Input
{% assign beatles = "John, Paul, George, Ringo" | split: ", " %}
{{ beatles | join: " and " }}
Output
John and Paul and George and Ringo
last
Returns the last item of an array.
Input
{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}
{{ my_array.last }}
Output
plums
Input
{% assign my_array = "zebra, octopus, giraffe, tiger" | split: ", " %}
{{ my_array.last }}
Output
tiger
lstrip
Removes all whitespaces (tabs, spaces, and newlines) from the beginning of a string. The filter does not affect spaces between words.
Input
A sentence before. {{ " So much room for activities! " | lstrip }} A sentence after.
Output
A sentence before. So much room for activities! A sentence after.
map
Important
We have overwritten the map filter so it will not work in the standard way. Visit the reference for the platformOS map filter to learn more.
minus
Subtracts a number from another number.
Input
{{ 4 | minus: 2 }}
Output
2
Input
{{ 16 | minus: 4 }}
Output
12
Input
{{ 183.357 | minus: 12 }}
Output
171.357
modulo
Returns the remainder of a division operation.
Input
{{ 3 | modulo: 2 }}
Output
1
Input
{{ 24 | modulo: 7 }}
Output
3
Input
{{ 183.357 | modulo: 12 }}
Output
3.357
newline_to_br
Replaces every newline (\n) with an HTML line break (<br>).
Input
{% capture string_with_newlines %}
Hello
there
{% endcapture %}
{{ string_with_newlines | newline_to_br }}
Output
<br />
Hello<br />
there<br />
plus
Adds a number to another number.
Input
{{ 4 | plus: 2 }}
Output
6
Input
{{ 16 | plus: 4 }}
Output
20
Input
{{ 183.357 | plus: 12 }}
Output
195.357
prepend
Adds the specified string to the beginning of another string.
Input
{{ "apples, oranges, and bananas" | prepend: "Some fruit: " }}
Output
Some fruit: apples, oranges, and bananas
You can also prepend variables:
Input
{% assign url = "example.com" %}
{{ "/index.html" | prepend: url }}
Output
example.com/index.html
remove
Removes every occurrence of the specified substring from a string.
Input
{{ "I strained to see the train through the rain" | remove: "rain" }}
Output
I sted to see the t through the
remove_first
Removes only the first occurrence of the specified substring from a string.
Input
{{ "I strained to see the train through the rain" | remove_first: "rain" }}
Output
I sted to see the train through the rain
replace
Replaces every occurrence of an argument in a string with the second argument.
Input
{{ "Take my protein pills and put my helmet on" | replace: "my", "your" }}
Output
Take your protein pills and put your helmet on
replace_first
Replaces only the first occurrence of the first argument in a string with the second argument.
Input
{% assign my_string = "Take my protein pills and put my helmet on" %}
{{ my_string | replace_first: "my", "your" }}
Output
Take your protein pills and put my helmet on
reverse
Reverses the order of the items in an array. reverse cannot reverse a string.
Input
{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}
{{ my_array | reverse | join: ", " }}
Output
plums, peaches, oranges, apples
reverse cannot be used directly on a string, but you can split a string into an array, reverse the array and rejoin it by chaining together filters:
Input
{{ "Ground control to Major Tom." | split: "" | reverse | join: "" }}
Output
.moT rojaM ot lortnoc dnuorG
round
Rounds an input number to the nearest integer or, if a number is specified as an argument, to that number of decimal places.
Input
{{ 1.2 | round }}
Output
1
Input
{{ 2.7 | round }}
Output
3
Input
{{ 183.357 | round: 2 }}
Output
183.36
rstrip
Removes all whitespace (tabs, spaces, and newlines) from the right side of a string.
Input
A sentence before. {{ " So much room for activities! " | rstrip }} A sentence after.
Output
A sentence before. So much room for activities! A sentence after.
size
Returns the number of characters in a string, the number of items in an array, or the number of bytes needed to store the integer in memory. size can also be used with dot notation (for example, 42). This allows you to use size inside tags such as conditionals.
Input
{{ "Ground control to Major Tom." | size }}
Output
28
Input
{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}
{{ my_array | size }}
Output
4
Using dot notation:
{% if site.pages.size > 10 %}
This is a big website!
{% endif %}
slice
Returns a substring of 1 character beginning at the index specified by the argument passed in. An optional second argument specifies the length of the substring to be returned.
String indices are numbered starting from 0.
Input
{{ "Liquid" | slice: 0 }}
Output
L
Input
{{ "Liquid" | slice: 2 }}
Output
q
Input
{{ "Liquid" | slice: 2, 5 }}
Output
quid
If the first parameter is a negative number, the indices are counted from the end of the string:
Input
{{ "Liquid" | slice: -3, 2 }}
Output
ui
sort
Sorts items in an array by a property of an item in the array. The order of the sorted array is case-sensitive, meaning all capitalized strings will come before any lowercase strings.
Input
{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " %}
{{ my_array | sort | join: ", " }}
Output
Sally Snake, giraffe, octopus, zebra
sort_natural
Sorts items in an array by a property of an item in the array. The order of the sorted array is case-insensitive.
Input
{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " %}
{{ my_array | sort_natural | join: ", " }}
Output
giraffe, octopus, Sally Snake, zebra
split
Divides an input 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
{% assign beatles = "John, Paul, George, Ringo" | split: ", " %}
{% for member in beatles %}
{{ member }}
{% endfor %}
Output
John
Paul
George
Ringo
strip
Removes all whitespace (tabs, spaces, and newlines) from both the left and right side of a string. It does not affect spaces between words.
Input
A sentence before. {{ " So much room for activities! " | strip }} A sentence after.
Output
A sentence before. So much room for activities! A sentence after.
strip_html
Removes any HTML tags from a string.
Input
{{ "Have <em>you</em> read <strong>Ulysses</strong>?" | strip_html }}
Output
Have you read Ulysses?
strip_newlines
Removes any newline characters (line breaks) from a string.
Input
{% capture string_with_newlines %}
Hello
there
{% endcapture %}
{{ string_with_newlines | strip_newlines }}
Output
Hellothere
times
Multiplies a number by another number.
Input
{{ 3 | times: 2 }}
Output
6
Input
{{ 24 | times: 7 }}
Output
168
Input
{{ 183.357 | times: 12 }}
Output
2200.284
truncate
truncate shortens a string down to the number of characters passed as a parameter. If the number of characters specified is less than the length of the string, an ellipsis (…) is appended to the string and is included in the character count.
Input
{{ "Ground control to Major Tom." | truncate: 20 }}
Output
Ground control to...
Custom ellipsis
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
{{ "Ground control to Major Tom." | truncate: 25, ", and so on" }}
Output
Ground control, and so on
No ellipsis
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
{{ "Ground control to Major Tom." | truncate: 20, "" }}
Output
Ground control to Ma
truncatewords
Shortens a string down to the number of words passed as the 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
{{ "Ground control to Major Tom." | truncatewords: 3 }}
Output
Ground control to...
Custom ellipsis
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
{{ "Ground control to Major Tom." | truncatewords: 3, "--" }}
Output
Ground control to--
No ellipsis
You can avoid showing trailing characters by passing a blank string as the second parameter:
Input
{{ "Ground control to Major Tom." | truncatewords: 3, "" }}
Output
Ground control to
uniq
Removes any duplicate elements in an array.
Input
{% assign my_array = "ants, bugs, bees, bugs, ants" | split: ", " %}
{{ my_array | uniq | join: ", " }}
Output
ants, bugs, bees
upcase
Makes each character in a string uppercase. It has no effect on strings which are already all uppercase.
Input
{{ "Parker Moore" | upcase }}
Output
PARKER MOORE
Input
{{ "TESLA" | upcase }}
Output
TESLA
url_decode
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
url_encode
Converts any URL-unsafe characters in a string into percent-encoded characters.
Input
{{ "john@liquid.com" | url_encode }}
Output
john%40liquid.com
Input
{{ "Thomas Edison" | url_encode }}
Output
Thomas+Edison
where
Creates an array including only the objects with a given property value, or any truthy value by default.
In this example, assume that 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
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 %}
Output
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
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 %}
Output
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
{% assign new_shirt = products | where: "type", "shirt" | first %}
Featured product: {{ new_shirt.title }}
Output
Featured product: Hawaiian print sweater vest