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.

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.