Iterating a loop
Run blocks of code repeatedly.
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.
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products -%}
{{ product }}
{% endfor -%}
hat
shirt
pants
You can also loop over a range of numbers. The range can be defined by both literal and variable numbers.
{% assign num = 5 -%}
{% for i in (3..num) -%}
{{ i }}
{% endfor -%}
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.
<!-- if products = [] -->
{% for product in products %}
{{ product }}
{% else %}
The collection is empty.
{% endfor %}
The collection is empty.
break
Causes the loop to stop iterating and exit.
{% 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.
{% for i in (1..5) -%}
{% if i == 4 -%}
{% continue -%}
{% else -%}
{{ i }}
{% endif -%}
{% endfor -%}
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.
<!-- if array = [1,2,3,4,5,6] -->
{% for item in array limit:2 -%}
{{ item }}
{% endfor -%}
1
2
offset
Begins the loop at the specified index.
<!-- if array = [1,2,3,4,5,6] -->
{% for item in array offset:2 -%}
{{ item }}
{% endfor -%}
3
4
5
6
reversed
Reverses the order of the loop (note, this parameter’s spelling is different from the filter reverse
).
<!-- if array = [1,2,3,4,5,6] -->
{% for item in array reversed -%}
{{ item }}
{% endfor -%}
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.
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products %}
{% if forloop.first == true %}
First time through!
{% else %}
Not the first time.
{% endif %}
{% endfor %}
First time through!
Not the first time.
Not the first time.
forloop.index
Returns the current index of the for
loop, starting at 1.
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products %}
{{ forloop.index }}
{% endfor %}
1 2 3
forloop.index0
Returns the current index of the for
loop, starting at 0.
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products %}
{{ forloop.index0 }}
{% endfor %}
0 1 2
forloop.last
Returns true
if it’s the last iteration of the for
loop. Returns false
otherwise.
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products %}
{% if forloop.last == true %}
This is the last iteration!
{% else %}
Keep going...
{% endif %}
{% endfor %}
Keep going...
Keep going...
This is the last iteration!
forloop.length
Returns the number of iterations of the loop.
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products %}
{% if forloop.first %}
This collection has {{ forloop.length }} products:
{% endif %}
{{ product }}
{% endfor %}
This collection has 3 products:
hat
shirt
pants
forloop.rindex
Returns forloop.index
in reverse order.
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products %}
{{ forloop.rindex }}
{% endfor %}
3 2 1
forloop.rindex0
Returns forloop.index0
in reverse order.
<!-- if products = ["hat", "shirt", "pants"] -->
{% for product in products %}
{{ forloop.rindex0 }}
{% endfor %}
2 1 0
Find a typo? Something is wrong in this documentation? Fork and edit it!