Controlling the flow
Use logic to follow different code paths in your templates.
Operators and control flow tags use logic to follow different code paths in your templates. They are denoted by curly braces and percent signs: {%
and %}
.
{% if title == "Awesome title" %}
This title is awesome!
{% endif %}
This title is awesome!
The markup used in tags does not produce any visible text, but it will still print a blank line in your rendered HTML. Include a hyphen in your tag syntax {%-
and -%}
, and we’ll strip the generated whitespace from your HTML.
Operators
Operators are useful for testing logic and performing comparisons.
== |
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 |
increment |
creates a new variable equal to 0 and increases its value by one |
decrement |
creates a new variable equal to -1 and decreases its value by one |
You can use multiple operators in a tag. 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 and will prevent your tags from working.
contains
Checks for the presence of a substring inside a string.
{% if "Awesome content" contains "Awesome" %}
This content is awesome.
{% endif %}
This content is awesome.
It can also check for the presence of a string in an array of strings.
<!-- if tags = ["Awesome", "Fun", "Cool"] -->
{% if tags contains "Awesome" %}
This array is awesome.
{% endif %}
This array is awesome.
Keep in mind, contains
can only search strings. You cannot use it to check for an object in an array of objects.
increment
Creates a new number variable, and increases its value by one every time it is called. The initial value is 0. Unlike other operators which require two operands, increment
only requires one.
{% increment my_counter %}
{% increment my_counter %}
{% increment my_counter %}
0
1
2
Variables created through the increment
tag are independent from variables created through assign
or capture
. In the example below, a variable named var
is created through assign
. The increment
tag is then used several times on a variable with the same name. Note that the increment
tag does not affect the value of var
that was created through assign
.
{% assign var = 10 -%}
{% increment var %}
{% increment var %}
{% increment var %}
{{ var }}
0
1
2
10
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
Like increment
, variables declared inside decrement
are independent from variables created through assign
or capture
.
Control flow tags
Control flow tags can change the information you show using programming logic.
if
Executes a block of code only if a certain condition is true
or evaluates to “truthy”.
<!-- if title = "Awesome title" -->
{% if title == "Awesome title" %}
This title is awesome!
{% endif %}
This title is awesome!
unless
Executes a block of code only if a certain condition is false
or evaluates to “truthy” - the opposite of if
.
<!-- if product.title = "Ugly Shoes" -->
{% unless product.title == "Awesome Shoes" %}
These shoes are not awesome.
{% endunless %}
These shoes are not awesome.
This would be the equivalent of the following:
{% if product.title != "Awesome Shoes" %}
These shoes are not awesome.
{% endif %}
These shoes are not awesome.
elsif/else
Adds more conditions within an if
or unless
block.
<!-- If customer.name = "anonymous" -->
{% if customer.name == "jack" -%}
Hi Jack!
{% elsif customer.name == "nancy" -%}
Hi Nancy!
{% else -%}
Hi Stranger!
{% endif -%}
Hi Stranger!
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
raw
Temporarily disables tag processing. This is useful for generating content (e.g., Mustache, Handlebars) which uses conflicting syntax.
{% raw %}
In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not.
{% endraw %}
In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not.
comment
Allows you to leave un-rendered code inside a template. Any text within the opening and closing comment blocks will not be printed, and any template code within will not be executed.
Anything between {% comment %} and {% endcomment %} tags is turned into a comment.
Anything between tags is turned into a comment.
Find a typo? Something is wrong in this documentation? Fork and edit it!