Controlling the flow

Change the information you display using programming logic.

Control flow tags use logic to follow different code paths in your templates. They are denoted by curly braces and percent signs: {% and %}.

Input
{% if product.title == "Awesome Shoes" %}
  These shoes are awesome!
{% endif %}
Output
These shoes are 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.

Input
{% if "Awesome product" contains "Awesome" %}
  This product's title contains the word "Awesome".
{% endif %}
Output
This product's title contains the word "Awesome".

It can also check for the presence of a string in an array of strings.

Input
{% if ["Awesome", "Fun", "Cool"] contains "Awesome" %}
  This product has been tagged with "Awesome".
{% endif %}
Output
This product has been tagged with "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.

Input
{% increment my_counter %}
{% increment my_counter %}
{% increment my_counter %}
Output
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.

Input
{% assign var = 10 %}
{% increment var %}
{% increment var %}
{% increment var %}
{{ var }}
Output
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.

Input
{% decrement my_counter %}
{% decrement my_counter %}
{% decrement my_counter %}
Output
-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.

unless

Executes a block of code only if a certain condition is false or evaluates to falsy - the opposite of if.

Input
<!-- if product.title = "Ugly Shoes" -->
{% unless product.title == "Awesome Shoes" %}
  These shoes are not awesome.
{% endunless %}
Output
These shoes are not awesome.

This would be the equivalent of the following:

{% if product.title != "Awesome Shoes" %}
  These shoes are not awesome.
{% endunless %}

elsif/else

Adds more conditions within an if or unless block.

Input
<!-- If customer.name = "anonymous" -->
{% if customer.name == "jack" %}
  Hi Jack!
{% elsif customer.name == "nancy" %}
  Hi Nancy!
{% else %}
  Hi Stranger!
{% endif %}
Output
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.

Input
{% 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 %}
Output
This is a cake

raw

Temporarily disables tag processing. This is useful for generating content (e.g., Mustache, Handlebars) which uses conflicting syntax.

Input
{% raw %}
  In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not.
{% endraw %}
Output
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.

Input
Anything between {% comment %} and {% endcomment %} tags is turned into a comment.
Output
Anything between &nbsp;tags is turned into a comment.

Next steps

Now that you know how to control the flow, learn how to run block of code repeatedly.

Iterating a loop Ask a question