Interation

Iteration tags repeatedly run blocks of code.

for

Renders an expression for every item in an array.

You can do a maximum of 50 iterations with a for loop. If you need to iterate over more than 50 items, then use the paginate tag to split the items over multiple pages.

๐Ÿ“˜

Tip

Every for loop has an associated forloop object with information about the loop.

{% for variable in array %}
  expression
{% endfor %}
  • variable: The current item in the array.
  • array: The array to iterate over.
  • expression: The expression to render for each iteration.
{% for product in collection.products %}
  {{ product.title }}
{% endfor %}
{
  "collection": {
    "products": [
      {
        "title": "Fit 3 Denim Shirt"
      },
      {
        "title": "Ace Cashmere Beanie"
      },
      {
        "title": "Oriental Intense EDP"
      },
      {
        "title": "Boiler Jumpsuit"
      }
    ]
  }
}
Fit 3 Denim Shirt
Ace Cashmere Beanie
Oriental Intense EDP
Boiler Jumpsuit

for tag parameters

limit

{% for variable in array limit: number %}
  expression
{% endfor %}

You can limit the number of iterations using the limit parameter.

{% for product in collection.products limit: 2 %}
  {{ product.title }}
{% endfor %}
{
  "collection": {
    "products": [
      {
        "title": "Fit 3 Denim Shirt"
      },
      {
        "title": "Ace Cashmere Beanie"
      },
      {
        "title": "Oriental Intense EDP"
      },
      {
        "title": "Boiler Jumpsuit"
      }
    ]
  }
}
Fit 3 Denim Shirt
Ace Cashmere Beanie

offset

{% for variable in array offset: number %}
  expression
{% endfor %}

You can specify a 1-based index to start iterating using the offset parameter.

{% for product in collection.products offset: 2 %}
  {{ product.title }}
{% endfor %}
{
  "collection": {
    "products": [
      {
        "title": "Fit 3 Denim Shirt"
      },
      {
        "title": "Ace Cashmere Beanie"
      },
      {
        "title": "Oriental Intense EDP"
      },
      {
        "title": "Boiler Jumpsuit"
      }
    ]
  }
}
Oriental Intense EDP
Boiler Jumpsuit

range

{% for variable in (number..number) %}
  expression
{% endfor %}

Instead of iterating over specific items in an array, you can specify a numeric range.

๐Ÿ“˜

Note

You can define the range using both literal and variable values.

{% for i in (1..5) %}
  {{ i }}
{% endfor %}

{% assign lower_limit = 2 %}
{% assign upper_limit = 5 %}

{% for i in (lower_limit..upper_limit) %}
  {{ i }}
{% endfor %}
1
2
3
4
5

2
3
4
5

reversed

{% for variable in array reversed %}
  expression
{% endfor %}

You can iterate in reverse order using the reversed parameter.

{% for product in collection.products reversed %}
  {{ product.title }}
{% endfor %}
{
  "collection": {
    "products": [
      {
        "title": "Fit 3 Denim Shirt"
      },
      {
        "title": "Ace Cashmere Beanie"
      },
      {
        "title": "Oriental Intense EDP"
      },
      {
        "title": "Boiler Jumpsuit"
      }
    ]
  }
}
Boiler Jumpsuit
Oriental Intense EDP
Ace Cashmere Beanie
Fit 3 Denim Shirt

forloop

Information about a parent for loop.

PropertiesTypeDescription
firstbooleanReturns true if the current iteration is the first. Returns false if not.
lastbooleanReturns true if the current iteration is the last. Returns false if not.
indexnumberThe 1-based index of the current iteration.
index0numberThe 0-based index of the current iteration.
lengthnumberThe total number of iterations in the loop.
rindexnumberThe 1-based index of the current iteration, in reverse order.
rindex0numberThe 0-based index of the current iteration, in reverse order.
{
  "first": true,
  "last": false,
  "index": 1,
  "index0": 0,
  "rindex": 4,
  "rindex0": 3,
  "length": 4
}

use the forloop object

{% for i in (1..5) %}
  {% if forloop.length > 0 %}
    {{ i }}{% unless forloop.last %},{% endunless %}
  {% endif %}
{% endfor %}
1, 2, 3, 4, 5

else

Allows you to specify a default expression to execute when a for loop has zero length.

{% for variable in array %}
  first_expression
{% else %}
  second_expression
{% endfor %}
  • variable: The current item in the array.
  • array: The array to iterate over.
  • first_expression: The expression to render for each iteration.
  • second_expression: The expression to render if the loop has zero length.
{% for product in collection.products %}
  {{ product.title }}
{% else %}
  There are no products in this collection.
{% endfor %}
{
  "collection": {
    "products": []
  }
}
There are no products in this collection.

break

Stops a for loop from iterating.

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

continue

Causes a for loop to skip to the next iteration.

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

cycle

Loops through a group of strings and outputs them one at a time for each iteration of a for loop.

The cycle tag must be used inside a for loop.

๐Ÿ“˜

Tip

Use the cycle tag to output text in a predictable pattern. For example, to apply odd/even classes to rows in a table.

{% cycle string, string, ... %}
{% for i in (1..5) %}
  {% cycle 'one', 'two', 'three' %}
{% endfor %}
one
two
three
one
two

Create unique cycle groups

{% cycle string: string, string, ... %}

If you include multiple cycle tags with the same parameters, in the same template, then each set of tags is treated as the same group. This means that it's possible for a cycle tag to output any of the provided strings, instead of always starting at the first string. To account for this, you can specify a group name for each cycle tag.

<!-- Iteration 1 -->
{% for i in (1..5) %}
  {% cycle 'one', 'two', 'three' %}
{% endfor %}

<!-- Iteration 2 -->
{% for i in (1..5) %}
  {% cycle 'one', 'two', 'three' %}
{% endfor %}

<!-- Iteration 3 -->
{% for i in (1..5) %}
  {% cycle 'group_1': 'one', 'two', 'three' %}
{% endfor %}

<!-- Iteration 4 -->
{% for i in (1..5) %}
  {% cycle 'group_2': 'one', 'two', 'three' %}
{% endfor %}
<!-- Iteration 1 -->
one
two
three
one
two

<!-- Iteration 2 -->
three
one
two
three
one

<!-- Iteration 3 -->
one
two
three
one
two

<!-- Iteration 4 -->
one
two
three
one
two

tablerow

Generates HTML table rows for every item in an array.

The tablerow tag must be wrapped in HTML <table> and </table> tags.

๐Ÿ“˜

Tip

Every tablerow loop has an associated tablerowloop object with information about the loop.

{% tablerow variable in array %}
  expression
{% endtablerow %}
  • variable: The current item in the array.
  • array: The array to iterate over.
  • expression: The expression to render.
<table>
  {% tablerow product in collection.products %}
    {{ product.title }}
  {% endtablerow %}
</table>
{
  "collection": {
    "products": [
      {
        "title": "Fit 3 Denim Shirt"
      },
      {
        "title": "Ace Cashmere Beanie"
      },
      {
        "title": "Oriental Intense EDP"
      },
      {
        "title": "Boiler Jumpsuit"
      }
    ]
  }
}
<table>
  <tbody>
    <tr class="row1">
      <td class="col1">Fit 3 Denim Shirt</td>
      <td class="col2">Ace Cashmere Beanie</td>
      <td class="col3">Oriental Intense EDP</td>
      <td class="col4">Boiler Jumpsuit</td>
    </tr>
  </tbody>
</table>

tablerow tag parameters

cols

{% tablerow variable in array cols: number %}
  expression
{% endtablerow %}

You can define how many columns the table should have using the cols parameter.

<table>
  {% tablerow product in collection.products cols: 2 %}
    {{ product.title }}
  {% endtablerow %}
</table>
{
  "collection": {
    "products": [
      {
        "title": "Fit 3 Denim Shirt"
      },
      {
        "title": "Ace Cashmere Beanie"
      },
      {
        "title": "Oriental Intense EDP"
      },
      {
        "title": "Boiler Jumpsuit"
      }
    ]
  }
}
<table>
  <tbody>
    <tr class="row1">
      <td class="col1">Fit 3 Denim Shirt</td>
      <td class="col2">Ace Cashmere Beanie</td>
    </tr>
    <tr class="row2">
      <td class="col1">Oriental Intense EDP</td>
      <td class="col2">Boiler Jumpsuit</td>
    </tr>
  </tbody>
</table>

limit

{% tablerow variable in array limit: number %}
  expression
{% endtablerow %}

You can limit the number of iterations using the limit parameter.

<table>
  {% tablerow product in collection.products limit: 3 %}
    {{ product.title }}
  {% endtablerow %}
</table>
{
  "collection": {
    "products": [
      {
        "title": "Fit 3 Denim Shirt"
      },
      {
        "title": "Ace Cashmere Beanie"
      },
      {
        "title": "Oriental Intense EDP"
      },
      {
        "title": "Boiler Jumpsuit"
      }
    ]
  }
}
<table>
  <tbody>
    <tr class="row1">
      <td class="col1">Fit 3 Denim Shirt</td>
      <td class="col2">Ace Cashmere Beanie</td>
      <td class="col3">Oriental Intense EDP</td>
    </tr>
  </tbody>
</table>

offset

{% tablerow variable in array offset: number %}
  expression
{% endtablerow %}

You can specify a 1-based index to start iterating using the offset parameter.

<table>
  {% tablerow product in collection.products offset: 1 %}
    {{ product.title }}
  {% endtablerow %}
</table>
{
  "collection": {
    "products": [
      {
        "title": "Fit 3 Denim Shirt"
      },
      {
        "title": "Ace Cashmere Beanie"
      },
      {
        "title": "Oriental Intense EDP"
      },
      {
        "title": "Boiler Jumpsuit"
      }
    ]
  }
}
<table>
  <tbody>
    <tr class="row1">
      <td class="col1">Ace Cashmere Beanie</td>
      <td class="col2">Oriental Intense EDP</td>
      <td class="col3">Boiler Jumpsuit</td>
    </tr>
  </tbody>
</table>

tablerowloop

Information about a parent tablerow loop.

PropertiesTypeDescription
firstnumberReturns 1 if the current iteration is the first. Returns 0 if not.
lastnumberReturns 1 if the current iteration is the last. Returns 0 if not.
indexnumberThe 1-based index of the current iteration.
index0numberThe 0-based index of the current iteration.
lengthnumberThe total number of iterations in the loop.
rindexnumberThe 1-based index of the current iteration, in reverse order.
rindex0numberThe 0-based index of the current iteration, in reverse order.
{
  "first": 1,
  "last": 0,
  "index": 1,
  "index0": 0,
  "rindex": 4,
  "rindex0": 3,
  "length": 4
}

paginate

Splits an array's items across multiple pages.

Because for loops are limited to 50 iterations per page, you need to use the paginate tag to iterate over an array that has more than 50 items. The following arrays can be paginated:

Within the paginate tag, you have access to the paginate object. You can use this object to build page navigation.

{% paginate array by page_size %}
  {% for item in array %}
    forloop_content
  {% endfor %}
{% endpaginate %}
  • array: The array to be looped over.
  • page_size: The number of array items to include per page, between 1 and 50.
  • item: An item in the array being looped.
  • forloop_content: Content for each loop iteration.
{% paginate collection.products by 8 %}
  {% for product in collection.products %}
    {{ product.title }}
  {% endfor %}
{% endpaginate %}
{
  "collection": {
    "products": [
      {
        "title": "Fit 3 Denim Shirt"
      },
      {
        "title": "Ace Cashmere Beanie"
      },
      {
        "title": "Oriental Intense EDP"
      },
      {
        "title": "Boiler Jumpsuit"
      }
    ],
    "products_count": 16
  }
}
Fit 3 Denim Shirt
Ace Cashmere Beanie
Oriental Intense EDP
Boiler Jumpsuit