Liquid Tags: Loops

Last updated on June 18, 2024

This article discusses the following topics:

  • for
  • cycle
  • ifchanged
  • tablerow

for

Liquid allows loops over collections to iterate over arrays, hashes, and ranges of integers.

Iterating Over an Array

Iterating Over a Hash

When iterating a hash, item[0] contains the key, and item[1] contains the value:

Instead of looping over an existing collection, you can also loop through a range of numbers. Ranges look like — parentheses containing a start value, two periods, and an end value. The start and end values must be integers or expressions that resolve to integers.

Input if item.quantity is 4

Output

Breaking and Continuing

You can exit a loop early with the following tags:

  • : immediately end the current iteration, and continue the loop with the next value.
  • : immediately end the current iteration, then completely end the loop.

These are only useful when combined with an statement.

Helper Variables

During every loop, the following helper variables are available for different styling needs:

VariableDescription
forloop.length
The length of the entire for loop.
forloop.index
The index of the current iteration.
forloop.index0The index of the current iteration (zero-based).
forloop.rindexReturns number of remaining items.
forloop.rindex0Returns number of remaining items (zero-based).
forloop.firstIs this the first iteration?
forloop.lastIs this the last iteration?
forloop.parentloopProvides access to the parent loop, if present.

Find examples on the Liquid Objects page.

Optional Arguments

There are several optional arguments to the tag that can influence which items you receive in your loop and what order they appear:

  • lets you restrict how many items you get.
  • lets you start the collection with the nth item.
  • iterates over the collection from last to first.

Restricting Elements

array = [1,2,3,4,5,6]

Output

Reversing the Loop

Handling an Empty Collection

A loop can take an optional clause to display a block of text when there are no items in the collection:

items => []

cycle

Loops through a group of strings and outputs them in the order that they were passed as parameters. Each time is called, the next string that was passed as a parameter is output.

will result in:

Though is often used within a loop block, it also works on its own by placing multiple copies of the tag on the page. Liquid treats each tag as part of the same group, even if their contents differ.

will result in:

If you want total control over groups, you can optionally specify the group's name. This can even be a variable.

will result in:

Liquid assumes that each tag without a name is part of the same nameless group. For example:

will result in:

ifchanged

The tag is typically called inside a loop because it executes a block of code but only outputs the result if this is the first time it was called or if the previous call had a different result.

Input

Output

tablerow

Generates rows for an HTML table. Must be wrapped in opening and closing HTML tags. The tablerowloop object describes the full list of attributes available within a .

Input Output

tablerow tag parameters

cols

Defines how many columns the tables should have.

Input
Output

limit

Exits the loop after a specific index.

offset

Starts the loop at a specific index.

range

Defines a range of numbers to loop through. Both literal and variable numbers can define the range.

Note

This topic is a compilation of knowledge found at Shopify Themes, Liquid Documentation, Liquid Gem Documentation, and Liquid for Designers.

Have a suggestion for this page?

Didn't quite find what you are looking for or have feedback on how we can make the content better then we would love to hear from you. Please provide us feedback and we will get back to you shortly.