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, or the default_pagination filter, to build page navigation.

Syntax

{% paginate array by page_size %}

{% for item in array %}

forloop_content

{% endfor %}

{% endpaginate %}

The `paginate` tag allows the user to paginate to the 25,000th item in the array and no further. To reach items further in

the array the array should be filtered further before paginating. See

[Pagination Limits](/themes/best-practices/performance/platform#pagination-limits) for more information.

array

The array to be looped over.

page_size

The number of array items to include per page, between 1 and 250.

item

An item in the array being looped.

forloop_content

Content for each loop iteration.

{% paginate collection.products by 5 %}

{% for product in collection.products -%}

{%- endfor %}

{% endpaginate %}

{% paginate collection.products by 5 %}
  {% for product in collection.products -%}
    {{ product.title }}
  {%- endfor %}

  {{- paginate | default_pagination }}
{% endpaginate %}

{
  "collection": {
    "products": [
      {
        "title": "Blue Mountain Flower"
      },
      {
        "title": "Charcoal"
      },
      {
        "title": "Crocodile tears"
      },
      {
        "title": "Dandelion milk"
      },
      {
        "title": "Draught of Immortality"
      }
    ],
    "products_count": 19
  }
}

Output

Blue Mountain Flower

Charcoal

Crocodile tears

Dandelion milk

Draught of Immortality

1 <a href="/services/liquid_rendering/resource?page=2&phcursor=eyJhbGciOiJIUzI1NiJ9.eyJzayI6InByb2R1Y3RfdGl0bGUiLCJzdiI6IkRyYXVnaHQgb2YgSW1tb3J0YWxpdHkiLCJkIjoiZiIsInVpZCI6NjgxNjg5OTU5NjM1MywibCI6NSwibyI6MCwiciI6IkNQIiwidiI6MSwicCI6Mn0.CHvTl4BkDruTti14tVbtdH3mHAKxGoh9QKJ5j4RDzLc" title="">2</a> <a href="/services/liquid_rendering/resource?page=3" title="">3</a> <a href="/services/liquid_rendering/resource?page=4" title="">4</a> <a href="/services/liquid_rendering/resource?page=2&phcursor=eyJhbGciOiJIUzI1NiJ9.eyJzayI6InByb2R1Y3RfdGl0bGUiLCJzdiI6IkRyYXVnaHQgb2YgSW1tb3J0YWxpdHkiLCJkIjoiZiIsInVpZCI6NjgxNjg5OTU5NjM1MywibCI6NSwibyI6MCwiciI6IkNQIiwidiI6MSwicCI6Mn0.CHvTl4BkDruTti14tVbtdH3mHAKxGoh9QKJ5j4RDzLc" title="">Next »</a>

Paginating setting arrays

To allow the pagination of product_list and collection_list settings to operate independently from other paginated lists on a page, these lists use a pagination query parameter with a unique key. The key is automatically assigned by the paginate tag, and you don't need to reference the key in your code. However, you can access the key using paginate.page_param.

Tip

To paginate two arrays independently without refreshing the entire page, you can use the Section Rendering API.

Limit data fetching

The limit parameter of the for tag controls the number of iterations, but not the amount of information fetched. Using the paginate tag with a matching page_size can reduce the data queried, leading to faster server response times.

For example, referencing collection.products will fetch up to 50 products by default, regardless of the forloop's limit parameter. Use paginate and set a page_size to limit the amount of data fetched, and opt not to display any pagination controls.

More data than requested in a specific section may be returned. Because of this, make sure to include both paginate and limit when using this technique.

{% paginate collection.products by 4 %}

{% for product in collection.products limit: 4 -%}

{%- endfor %}

{% endpaginate -%}

{% for product in collection.products limit: 4 -%}

{%- endfor -%}

{% paginate collection.products by 4 %}
  {% for product in collection.products limit: 4 -%}
    {{ product.title }}
  {%- endfor %}
{% endpaginate -%}

<!-- Less performant method -->
{% for product in collection.products limit: 4 -%}
  {{ product.title }}
{%- endfor -%}

{
  "collection": {
    "products": [
      {
        "title": "Blue Mountain Flower"
      },
      {
        "title": "Charcoal"
      },
      {
        "title": "Crocodile tears"
      },
      {
        "title": "Dandelion milk"
      }
    ],
    "products_count": 19
  }
}

Output

Blue Mountain Flower

Charcoal

Crocodile tears

Dandelion milk

Blue Mountain Flower

Charcoal

Crocodile tears

Dandelion milk

paginate tag parameters

window_size

Syntax

{% paginate collection.products by 3, window_size: 1 %}

Set the window size of the pagination. The window size is the number of pages that should be visible in the pagination navigation.

{% paginate collection.products by 3, window_size: 1 %}

{% for product in collection.products -%}

{%- endfor %}

{% endpaginate %}

{% paginate collection.products by 3, window_size: 1 %}
  {% for product in collection.products -%}
    {{ product.title }}
  {%- endfor %}

  {{- paginate | default_pagination }}
{% endpaginate %}

{
  "collection": {
    "products": [
      {
        "title": "Blue Mountain Flower"
      },
      {
        "title": "Charcoal"
      },
      {
        "title": "Crocodile tears"
      }
    ],
    "products_count": 19
  }
}

Output

Blue Mountain Flower

Charcoal

Crocodile tears

1 … <a href="/services/liquid_rendering/resource?page=7" title="">7</a> <a href="/services/liquid_rendering/resource?page=2&phcursor=eyJhbGciOiJIUzI1NiJ9.eyJzayI6InByb2R1Y3RfdGl0bGUiLCJzdiI6IkNyb2NvZGlsZSB0ZWFycyIsImQiOiJmIiwidWlkIjo2NzkyNjAyMzIwOTYxLCJsIjozLCJvIjowLCJyIjoiQ1AiLCJ2IjoxLCJwIjoyfQ.NlPFL_gIeSKYjsf9abaCAgLjdBYJ7YfNwRpdr-HpyN0" title="">Next »</a>

Was this page helpful?