Liquid:

Liquid is a flexible, safe language, and is used in many different environments. Liquid was created for use in Shopify stores, and is also used extensively on Jekyll websites. Over time, both Shopify and Jekyll have added their own objects, tags, and filters to Liquid. The most popular versions of Liquid that exist are Liquid, Shopify Liquid, and Jekyll Liquid.


Liquid cheat sheet:

liquid operators:

Symbol Description
== equals
!= does not equal
> greater than
< less than
>= greater than or equal to
<= less than or equal to
or logical or
and logical and
contains checks for the presence of a substring inside a string.

Order of operations:

In tags with more than one and or or operator, operators are checked in order from right to left. You cannot change the order of operations using parentheses — parentheses are invalid characters in Liquid and will prevent your tags from working.


Truthy and Falsy:

  Truthy Falsy
true  
false  
nil  
string  
empty string  
0  
integer  
float  
array  
empty array  
page  
EmptyDrop  

Types:

Liquid objects can have one of five types:

Title Code Description
String   Declare a string by wrapping a variable’s value in single or double quotes

Comment:

Code:

Anything you put between {% comment %} and {% endcomment %} tags is turned into a comment.

output:

Anything you put between tags is turned into a comment.


Control flow statements:

Title Description Code Output
If Executes a block of code only if a certain condition is true. {% if product.title == “Awesome Shoes” %} These shoes are awesome! {% endif %} These shoes are awesome!
unless Executes a block of code only if a certain condition is true. {% unless product.title == “Awesome Shoes” %}These shoes are not awesome.{% endunless %} These shoes are not awesome.
elsif / else Adds more conditions within an if or unless block. {% if customer.name == “kevin” %} Hey Kevin!{% elsif customer.name == “anonymous” %} Hey Anonymous!{% else %} Hi Stranger!{% endif %} Hey Anonymous!
case/when Creates a switch statement to compare a variable with different values. case initializes the switch statement, and when compares its values. {% assign handle = “cake” %}{% case handle %} {% when “cake” %} This is a cake {% when “cookie” %} This is a cookie {% else %} This is not a cake nor a cookie{% endcase %} This is a cake

Iteration statements:

Title Description Code Output
For loop Repeatedly executes a block of code. {% for product in collection.products %} {{ product.title }} {% endfor %} hat shirt pants
Break Causes the loop to stop iterating when it encounters the break tag. {% for i in (1..5) %} {% if i == 4 %} {% break %} {% else %} {{ i }} {% endif %}{% endfor %} 1 2 3
Continue Causes the loop to skip the current iteration when it encounters the continue tag. {% for i in (1..5) %} {% if i == 4 %} {% continue %} {% else %} {{ i }} {% endif %}{% endfor %} 1 2 3 5
Limit Limits the loop to the specified number of iterations. {% for item in array limit:2 %} {{ item }}{% endfor %} 1 2
Offset Begins the loop at the specified index. {% for item in array offset:2 %} {{ item }}{% endfor %} 3 4 5 6
Range Defines a range of numbers to loop through. The range can be defined by both literal and variable numbers. {% for i in (3..5) %} {{ i }}{% endfor %}{% assign num = 4 %}{% for i in (1..num) %} {{ i }}{% endfor %} 3 4 5
1 2 3 4      
Reversed Reverses the order of the loop. Note that this flag’s spelling is different from the filter reverse. {% for item in array reversed %} {{ item }}{% endfor %} 6 5 4 3 2 1
Cycle Loops through a group of strings and prints them in the order that they were passed as arguments. Each time cycle is called, the next string argument is printed. {% cycle “one”, “two”, “three” %}{% cycle “one”, “two”, “three” %}{% cycle “one”, “two”, “three” %}{% cycle “one”, “two”, “three” %} one
two
three
one
Cycle (parameters) cycle accepts a “cycle group” parameter in cases where you need multiple cycle blocks in one template. If no name is supplied for the cycle group, then it is assumed that multiple calls with the same parameters are one group. {% cycle “first”: “one”, “two”, “three” %}{% cycle “second”: “one”, “two”, “three” %}{% cycle “second”: “one”, “two”, “three” %}{% cycle “first”: “one”, “two”, “three” %} one
one
two
two
Tablerow Generates an HTML table. Must be wrapped in opening <table> and closing </table> HTML tags. <table>{% tablerow product in collection.products %} {{ product.title }}{% endtablerow %}</table> <table> <tr class="row1"> <td class="col1"> Cool Shirt </td> <td class="col2"> Alien Poster </td> <td class="col3"> Batman Poster </td> <td class="col4"> Bullseye Shirt </td> <td class="col5"> Another Classic Vinyl </td> <td class="col6"> Awesome Jeans </td> </tr></table>
Tablerow (parameters) cols: Defines how many columns the tables should have. {% tablerow product in collection.products cols:2 %} {{ product.title }}{% endtablerow %} <table> <tr class="row1"> <td class="col1"> Cool Shirt </td> <td class="col2"> Alien Poster </td> </tr> <tr class="row2"> <td class="col1"> Batman Poster </td> <td class="col2"> Bullseye Shirt </td> </tr> <tr class="row3"> <td class="col1"> Another Classic Vinyl </td> <td class="col2"> Awesome Jeans </td> </tr></table>

Raw:

Raw temporarily disables tag processing. This is useful for generating content (eg, Mustache, Handlebars) which uses conflicting syntax.


Variable:

To create a variable use the following methods:

Title Description Code Output
assign Creates a new variable. {% assign my_variable = 1 %} {{my_variable}} 1
capture Captures the string inside of the opening and closing tags and assigns it to a variable. Variables created through capture are strings. {% capture my_variable %}I am being captured.{% endcapture %}{{ my_variable }} I am being captured.
increment Creates a new number variable, and increases its value by one every time it is called. The initial value is 0. {% increment my_counter %}{% increment my_counter %}{% increment my_counter %} 0
1
2
decrement Creates a new number variable, and decreases its value by one every time it is called. The initial value is -1. {% decrement my_counter %}{% decrement my_counter %}{% decrement my_counter %} -1
-2
-3

Filters:

Title Description Code Output  
abs Returns the absolute value of a number. {{ -17 | abs }} 17  
append Concatenates two strings and returns the concatenated value. {{ “/my/fancy/url” | append: “.html” }} /my/fancy/url.html  
at_least Limits a number to a minimum value. {{ 4 | at_least: 5 }} 5  
at_most Limits a number to a maximum value. {{ 4 | at_most: 5 }} 4  
capitalize Makes the first character of a string capitalized. {{ “title” | capitalize }} 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. {{ 1.2 | ceil }} 2  
compact Removes any nil values from an array. In this example site.pages is an array in config.yml page which contains the categories of the page. If any page which do not contain the category will be displayed as an empty value in this array. By using compact the nil value of this array is removed. {% assign site_categories = site.pages | map: “category” | compact %}{% for category in site_categories %}- {{ category }}{% endfor %} - business
- celebrities
- lifestyle
- sports
- technology
 
concat Concatenates (joins together) multiple arrays. The resulting array contains all the items from the input arrays. {% 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
 
date Converts a timestamp into another date format. {{ article.published_at | date: “%a, %b %d, %y” }} Fri, Jul 20, 15  
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. {{ product_price | default: 2.99 }} 2.99  
divided_by Divides a number by another number. {{ 16 | divided_by: 4 }} 4  
downcase Makes each character in a string lowercase. It has no effect on strings which are already all lowercase. {{ “Parker Moore” | downcase }} parker moore  
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. {{ “Have you read ‘James & the Giant Peach’?” | escape }} Have you read &#39;James &amp; the Giant Peach&#39;?  
escape_once Escapes a string without changing existing escaped entities. It doesn’t change strings that don’t have anything to escape. {{ “1 < 2 & 3” | escape_once }} 1 &lt; 2 &amp; 3  
first Returns the first item of an array. {{ “Ground control to Major Tom.” | split: “ “ | first }} Ground  
floor Rounds the input down to the nearest whole number. Liquid tries to convert the input to a number before the filter is applied. {{ 1.2 | floor }} 1  
join Combines the items in an array into a single string using the argument as a separator. {% assign beatles = “John, Paul, George, Ringo” | split: “, “ %}{{ beatles | join: “ and “ }} John and Paul and George and Ringo  
last Returns the last item of an array. {{ “Ground control to Major Tom.” | split: “ “ | last }} Tom.  
lstrip Removes all whitespace (tabs, spaces, and newlines) from the left side of a string. It does not affect spaces between words. {{ “ So much room for activities! “ | lstrip }} So much room for activities!  
map Creates an array of values by extracting the values of a named property from another object. {% assign site_categories = site.pages | map: “category” | compact %}{% for category in site_categories %}- {{ category }}{% endfor %} - business
- celebrities
- lifestyle
- sports
- technology
 
minus Subtracts a number from another number. {{ 4 | minus: 2 }} 2  
modulo Returns the remainder of a division operation {{ 3 | modulo: 2 }} 1  
newline_to_br Replaces every newline in a string with an HTML line break. {% capture string_with_newlines %}Hello there{% endcapture %}{{ string_with_newlines | newline_to_br }}
Hello
there
 
plus Adds a number to another number. {{ 4 | plus: 2 }} 6  
prepend Adds the specified string to the beginning of another string. {{ “apples, oranges, and bananas” | prepend: “Some fruit: “ }} Some fruit: apples, oranges, and bananas  
remove Removes every occurrence of the specified substring from a string. {{ “I strained to see the train through the rain” | remove: “rain” }} I sted to see the t through the  
remove_first Removes only the first occurrence of the specified substring from a string. {{ “I strained to see the train through the rain” | remove_first: “rain” }} I sted to see the train through the rain  
replace Replaces every occurrence of the first argument in a string with the second argument. {{ “Take my protein pills and put my helmet on” | replace: “my”, “your” }} 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. {{ “Take my protein pills and put my helmet on” | replace_first: “my”, “your” }} Take your protein pills and put my helmet on  
reverse Reverses the order of the items in an array. reverse cannot reverse a string. {% assign my_array = “apples, oranges, peaches, plums” | split: “, “ %}{{ my_array | reverse | join: “, “ }} plums, peaches, oranges, apples  
round Rounds a number to the nearest integer or, if a number is passed as an argument, to that number of decimal places. {{ 1.2 | round }} 1  
rstrip Removes all whitespace (tabs, spaces, and newlines) from the right side of a string. It does not affect spaces between words {{ “ So much room for activities! “ | rstrip }} So much room for activities!  
size Returns the number of characters in a string or the number of items in an array. {{ “Ground control to Major Tom.” | size }} 28  
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. {{ “Liquid” | slice: 0 }} L  
sort Sorts items in an array in case-sensitive order. {% assign my_array = “zebra, octopus, giraffe, Sally Snake” | split: “, “ %}{{ my_array | sort | join: “, “ }} Sally Snake, giraffe, octopus, zebra  
sort_natural Sorts items in an array in case-insensitive order. {% assign my_array = “zebra, octopus, giraffe, Sally Snake” | split: “, “ %}{{ my_array | sort_natural | join: “, “ }} giraffe, octopus, Sally Snake, zebra  
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. {% assign beatles = “John, Paul, George, Ringo” | split: “, “ %}{% for member in beatles %} {{ member }}{% endfor %} John
Paul
George
Ringo
 
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. {{ “ So much room for activities! “ | strip }} So much room for activities!  
strip_html Removes any HTML tags from a string. {{ “Have you read Ulysses?” | strip_html }} Have you read Ulysses?  
strip_newlines Removes any newline characters (line breaks) from a string. {% capture string_with_newlines %}Hello there{% endcapture %}{{ string_with_newlines | strip_newlines }} Hellothere  
times Multiplies a number by another number. {{ 3 | times: 2 }} 6  
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. {{ “Ground control to Major Tom.” | truncate: 20 } Ground control to…  
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. {{ “Ground control to Major Tom.” | truncatewords: 3 }} Ground control to…  
uniq Removes any duplicate elements in an array. {% assign my_array = “ants, bugs, bees, bugs, ants” | split: “, “ %}{{ my_array | uniq | join: “, “ }} ants, bugs, bees  
upcase Makes each character in a string uppercase. It has no effect on strings which are already all uppercase. {{ “Parker Moore” | upcase }} PARKER MOORE  
url_decode Decodes a string that has been encoded as a URL or by url_encode. {{ “%27Stop%21%27+said+Fred” | url_decode }} ‘Stop!’ said Fred  
url_encode Converts any URL-unsafe characters in a string into percent-encoded characters. {{ “john@liquid.com” | url_encode }} john%40liquid.com  
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”. 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