Iterating a loop

For loops allow you to run blocks of code repeatedly. You can change the loop’s behavior with control tags and parameters, and within a loop, you can access attributes to control the iteration.

Repeatedly executes a block of code while iterating over an array.

Input 
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products -%}
  {{ product }}
{% endfor -%}
Output 
hat
shirt
pants

You can also loop over a range of numbers. The range can be defined by both literal and variable numbers.

Input 
{% assign num = 5 -%}
{% for i in (3..num) -%}
  {{ i }}
{% endfor -%}
Output 
3
4
5

Control tags

Within the for loop, you can use the else, break, and continue tags to control the iteration.

else

Specifies a fallback case for a for loop which will run if the loop has zero length.

Input 
<!-- if products = [] -->
{% for product in products %}
  {{ product }}
{% else %}
  The collection is empty.
{% endfor %}
Output 
The collection is empty.

break

Causes the loop to stop iterating and exit.

Input 
{% for i in (1..5) -%}
  {% if i == 4 -%}
    {% break -%}
  {% else -%}
    {{ i }}
  {% endif -%}
{% endfor -%}
Output 
1
  2
  3

continue

Causes the loop to skip the current iteration.

Input 
{% for i in (1..5) -%}
  {% if i == 4 -%}
    {% continue -%}
  {% else -%}
    {{ i }}
  {% endif -%}
{% endfor -%}
Output 
1
  2
  3
  5

Parameters

You can pass limit, offset, and reversed parameters into a for loop to change its starting position, ending position, or order, respectively.

limit

Limits the loop to the specified number of iterations.

Input 
<!-- if array = [1,2,3,4,5,6] -->
{% for item in array limit:2 -%}
  {{ item }}
{% endfor -%}
Output 
1
2

offset

Begins the loop at the specified index.

Input 
<!-- if array = [1,2,3,4,5,6] -->
{% for item in array offset:2 -%}
  {{ item }}
{% endfor -%}
Output 
3
4
5
6

reversed

Reverses the order of the loop (note, this parameter’s spelling is different from the filter reverse).

Input 
<!-- if array = [1,2,3,4,5,6] -->
{% for item in array reversed -%}
  {{ item }}
{% endfor -%}
Output 
6
5
4
3
2
1

Attributes

Within a for loop, the forloop object provides information about the loop.

forloop.first

Returns true if it’s the first iteration of the for loop. Returns false otherwise.

Input 
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products %}
  {% if forloop.first == true %}
    First time through!
  {% else %}
    Not the first time.
  {% endif %}
{% endfor %}
Output 
First time through!
Not the first time.
Not the first time.

forloop.index

Returns the current index of the for loop, starting at 1.

Input 
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products %}
  {{ forloop.index }}
{% endfor %}
Output 
1 2 3

forloop.index0

Returns the current index of the for loop, starting at 0.

Input 
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products %}
  {{ forloop.index0 }}
{% endfor %}
Output 
0 1 2

forloop.last

Returns true if it’s the last iteration of the for loop. Returns false otherwise.

Input 
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products %}
  {% if forloop.last == true %}
    This is the last iteration!
  {% else %}
    Keep going...
  {% endif %}
{% endfor %}
Output 
Keep going...
Keep going...
This is the last iteration!

forloop.length

Returns the number of iterations of the loop.

Input 
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products %}
  {% if forloop.first %}
    This collection has {{ forloop.length }} products:
  {% endif %}
  {{ product }}
{% endfor %}
Output 
This collection has 3 products:
hat
shirt
pants

forloop.rindex

Returns forloop.index in reverse order.

Input 
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products %}
  {{ forloop.rindex }}
{% endfor %}
Output 
3 2 1

forloop.rindex0

Returns forloop.index0 in reverse order.

Input 
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products %}
  {{ forloop.rindex0 }}
{% endfor %}
Output 
2 1 0

Find a typo? Something is wrong in this documentation? Fork and edit it!