Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 61 ยท Liquid Basics

Loops: for, break, limit, offset, forloop

Learn Shopify Liquid loops: the for tag, forloop object, limit, offset, reversed, ranges, else, break, continue, cycle, tablerow and paginate, with live examples.

Themes are full of repeated things: product cards in a grid, slides in a banner, links in a menu, options in a dropdown. You never write those by hand. You write one piece of markup and let a loop repeat it for every item in a list. In Liquid the loop tag is for, and it comes with a helper object called forloop that tells you where you are in the list.

In this lesson you will learn the for tag, its parameters (limit, offset, reversed), range loops, the else branch for empty lists, break and continue, cycle, tablerow, and how paginate fits in. The snippets target current Online Store 2.0 themes. Liquid is not tied to an Admin API version, so nothing here changes between API releases. Conditions inside loops use what you learned in Conditions: if, unless, case.

Real Liquid runs on Shopify's servers, so theme code is shown as read-only snippets here. The runnable examples use a small Liquid-style engine written in JavaScript. Its loop rules follow Liquid, but it is a teaching stand-in, not Shopify's implementation.

The for tag and the forloop object

A for loop names a variable for the current item and a list to walk through. Everything between for and endfor is rendered once per item.

LIQUID
<ul>
  {% for product in collection.products %}
    <li>{{ product.title }}</li>
  {% endfor %}
</ul>

The variable product exists only inside the loop. Inside it you also get a forloop object:

Property Meaning
forloop.index position, starting at 1
forloop.index0 position, starting at 0
forloop.rindex items left, counting the current one (last item is 1)
forloop.rindex0 items left after the current one (last item is 0)
forloop.first true on the first pass
forloop.last true on the final pass
forloop.length how many items the loop will run over
forloop.parentloop the forloop of the enclosing loop, or nil

forloop.first and forloop.last are what you use to avoid a trailing comma or to add a class to the first slide only. forloop.index0 is handy for zero-based data attributes.

LIQUID
{% for tag in product.tags %}{{ tag }}{% unless forloop.last %}, {% endunless %}{% endfor %}
flowchart TD
    S["Start: list has N items"] --> E{"Any items left?"}
    E -- no --> EL["Render else branch if present"]
    E -- yes --> B["Set item and forloop, render body"]
    B --> C{"break or continue?"}
    C -- break --> X["Leave the loop"]
    C -- continue --> E
    C -- neither --> E
    EL --> X

A for loop renders its body per item; break leaves early and continue skips to the next item.

limit, offset and reversed

Three optional parameters change which items the loop sees:

LIQUID
{% for product in collection.products limit: 4 %}โ€ฆ{% endfor %}
{% for product in collection.products limit: 4 offset: 4 %}โ€ฆ{% endfor %}
{% for product in collection.products reversed %}โ€ฆ{% endfor %}
  • limit: n stops after n items. It is the standard way to show "the first 4 products".
  • offset: n skips the first n items. limit and offset together give you a window.
  • reversed walks the list backwards. Limit and offset are applied first, then the chosen window is reversed.

There is also offset: continue, which starts a second loop where the previous loop over the same list stopped. It is rare in modern themes because sections and blocks are a better way to split content.

For big lists, still prefer asking for fewer items in the first place; see Liquid Performance later in the course.

Range loops

A pair of integers in parentheses makes a list on the fly. The numbers can come from variables too.

LIQUID
{% for i in (1..5) %}{{ i }} {% endfor %}
{% assign stars = 4 %}
{% for i in (1..5) %}
  <span class="star {% if i <= stars %}is-filled{% endif %}"></span>
{% endfor %}

Range loops are ideal for ratings, fixed-length placeholders and numbered steps. The ends must be whole numbers; a range such as (a..z) for letters does not work.

The else branch

If the list is empty (or nil), the loop body never runs. You can add an else inside the loop to say what to show instead:

LIQUID
{% for product in collection.products %}
  {% render 'product-card', product: product %}
{% else %}
  <p>No products in this collection yet.</p>
{% endfor %}

This else is part of the for tag; it runs when there were zero iterations, not when the loop finishes.

break and continue

  • {% break %} stops the loop completely.
  • {% continue %} skips the rest of this pass and jumps to the next item.

Use them with a condition. A typical use is to skip unavailable products, or to stop after you found the first match:

LIQUID
{% for variant in product.variants %}
  {% unless variant.available %}{% continue %}{% endunless %}
  {% assign first_available = variant %}
  {% break %}
{% endfor %}

Everything rendered before a break in the same pass stays in the output.

cycle

cycle prints the next value from a list each time it runs, wrapping around at the end. It is meant for alternating classes or column positions.

LIQUID
{% for product in collection.products %}
  <li class="{% cycle 'odd', 'even' %}">{{ product.title }}</li>
{% endfor %}

If you use several cycle tags that should not share one counter, give each its own group name: {% cycle 'header': 'a', 'b' %}. Without a group name, cycles with the same list of values share state. For simple stripes today, CSS selectors such as :nth-child(odd) are usually a better choice than server-side classes.

Try it: loops in a mini engine

The editor below has the small stand-in engine and runs templates over a list of five products. Try changing limit, offset, or the forloop.index0 == 3 test, then run again. Watch how the else branch, continue and break, cycle, and parentloop behave.

JS Loops in a mini Liquid engine

Press Run (or Ctrl + Enter) to see the console output here.

No output.

What is real here and what is not? The tags, parameters and forloop values mirror Liquid. The engine itself, its error handling and the output formatting are simplified, and it does not implement tablerow, paginate or offset: continue.

forloop values and pagination, in plain JavaScript

The second example needs no engine. First it prints every forloop value for a four-item list, so you can see how index, rindex and friends relate. Then it works out what paginate would compute for 23 products at 10 per page.

JS forloop values and the maths of paginate

Press Run (or Ctrl + Enter) to see the console output here.

No output.

tablerow

tablerow loops like for but wraps each item in table cells. It is occasionally used to make grids for emails or simple data tables.

LIQUID
<table>
  {% tablerow product in collection.products cols: 3 limit: 6 %}
    {{ product.title }}
  {% endtablerow %}
</table>

It supports cols, limit and offset, and gives you a tablerowloop object (with values such as col and row). The generated cells carry classes like row1 and col1. Today most themes build grids with CSS Grid and a plain for, so tablerow is mainly for real tabular data.

paginate: loops over big lists

Collections, search results, blog articles and some other lists are large. Shopify only gives you one page of them at a time, up to 50 items. To loop over a long list you wrap the loop in a paginate tag, and Shopify slices the list by the page query parameter in the URL.

LIQUID
{% paginate collection.products by 12 %}
  <ul>
    {% for product in collection.products %}
      <li>{{ product.title }}</li>
    {% endfor %}
  </ul>
  {% if paginate.pages > 1 %}
    {{ paginate | default_pagination }}
  {% endif %}
{% endpaginate %}

Inside the tag you get a paginate object with values such as paginate.pages, paginate.current_page, paginate.items, paginate.page_size, paginate.previous and paginate.next. The page size can be at most 50. Without paginate, a loop over collection.products only reaches the first page. The details of collection pages, filters and sorting come later in Collection Pages.

Common mistakes

  • Using the loop variable after endfor. It is gone. Save what you need with assign before leaving the loop.
  • Nested loops that multiply work. A loop of 50 products with an inner loop over all variants and an inner-inner loop over media does a lot. Move work out of loops when possible.
  • Forgetting that limit counts items after offset. limit: 4 offset: 4 shows items 5 to 8.
  • Mixing up the range number and the pass count. In (0..4) the variable runs 0 to 4, but forloop.index still starts at 1.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which forloop property is true only on the final pass of the loop?

    forloop.last is true on the last iteration. forloop.first is its opposite on the first pass; rindex counts down; length is the total number of items.
  2. 2. What does {% for p in products limit: 3 offset: 2 %} loop over?

    offset: 2 skips the first two items, and limit: 3 then takes three items, which are items 3, 4 and 5.
  3. 3. When does the else branch of a for loop run?

    The else belongs to the for tag and only renders when there were no items to loop over.
  4. 4. Why do you wrap a loop over collection.products in paginate?

    Shopify returns one page (at most 50 items) at a time. paginate chooses the page from the URL and gives you the paginate object for page links.
  5. 5. What is {% continue %} for?

    continue skips to the next item. break is the tag that leaves the loop entirely.

Summary

  • {% for item in list %} repeats its body per item and gives you forloop (index, index0, rindex, rindex0, first, last, length, parentloop).
  • limit, offset and reversed change which items the loop sees; limit and offset are applied before the reversal.
  • Range loops (1..n) work with whole numbers and variables; else handles empty lists.
  • break leaves the loop, continue skips an item, cycle alternates values.
  • tablerow builds table cells; paginate slices long lists (at most 50 per page) and provides the paginate object.

Next: Variables: assign, capture, increment