Liquid paginate: Split into multiple pages

When you have a long list of items, such as products, blog posts, or collections, displaying them all on a single page can make it overwhelming for users and slow down your Shopify store's loading time. This is where Shopify's paginate tag comes to the rescue. It allows you to split your content into multiple pages, improving user experience and site performance.

In this comprehensive guide, we'll delve into the intricacies of the paginate tag, exploring its syntax, parameters, and practical applications. 
The paginate tag works with the for tag to divide your content into different pages. It must wrap a for tag block that can loop through an array as displayed in the example taken below:

{% paginate collection.products by 5 %}
  {% for product in collection.products %}
    <!--show product details here -->
  {% endfor %}
{% endpaginate %}

The parameter called by is followed by an integer between 1 and 50 that could tell the paginate tag how many results it should output per page. Within paginate tags, you are allowed to access attributes of the paginate object. This includes the attributes to output the links, which are required to navigate within the created pages.

Now, let’s take a look at our instructional writing on Liquid paginate: Split into multiple pages to know more deeply about the use of ‘include’.

Liquid paginate: Split into multiple pages

• The use of Pagination
• How to enable Pagination
• About Liquid Attributes Available
• How to render the paginated Posts

The use of Pagination

It is very common, with many websites especially blogs, to break the main listing of posts up into smaller lists and show them over many pages. Then Jekyll offers a pagination plugin so you are able to automatically generate the appropriate files and folders you need for paginated listings.

How to enable Pagination

Please insert a line into the _config.yml file, which can specify how many items should be shown per page, to enable pagination for posts on your blog:

paginate: 5

The number should be the maximum number of posts you would like to display per page in the created site.

You might also want to specify the destination of the pagination pages:

paginate_path: "/blog/page:num/"

This will read in blog/index.html, send it every pagination page in Liquid as paginator and type in the output to blog/page:num/, the place that :num is the pagination page number, which starts with 2. In case a site has 12 posts and specifies paginate: 5, Jekyll will write blog/index.html with the first 5 posts, blog/page2/index.html with the following 5 posts and blog/page3/index.html with the last 2 posts into the destination directory.

About Liquid Attributes Available

The pagination plugin exposes the paginator liquid object with the attributes listed below:

How to render the paginated Posts

The next step you need to do is to actually show your posts in a list using the paginator variable that will be available to you now. You will propably want to do this in one of the main pages of your site. Here do we give you an example displayed below as a simple way of rendering paginated Posts in a HTML file:

---
layout: default
title: My Blog
---

<!-- This loops through the paginated posts -->
{% for post in paginator.posts %}
  <h1><a href="{{ post.url }}">{{ post.title }}</a></h1>
  <p class="author">
    <span class="date">{{ post.date }}</span>
  </p>
  <div class="content">
    {{ post.content }}
  </div>
{% endfor %}

<!-- Pagination links -->
<div class="pagination">
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path }}" class="previous">
      Previous
    </a>
  {% else %}
    <span class="previous">Previous</span>
  {% endif %}
  <span class="page_number ">
    Page: {{ paginator.page }} of {{ paginator.total_pages }}
  </span>
  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path }}" class="next">Next</a>
  {% else %}
    <span class="next ">Next</span>
  {% endif %}
</div>

The HTML snippet below should handle page one and render a list of every page with links to all except for the recent page.

{% if paginator.total_pages > 1 %}
<div class="pagination">
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path | relative_url }}">
      &laquo; Prev
    </a>
  {% else %}
    <span>&laquo; Prev</span>
  {% endif %}

  {% for page in (1..paginator.total_pages) %}
    {% if page == paginator.page %}
      <em>{{ page }}</em>
    {% elsif page == 1 %}
      <a href="{{ paginator.previous_page_path | relative_url }}">
        {{ page }}
      </a>
    {% else %}
      <a href="{{ site.paginate_path | relative_url | replace: ':num', page }}">
        {{ page }}
      </a>
    {% endif %}
  {% endfor %}

  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path | relative_url }}">
      Next &raquo;
    </a>
  {% else %}
    <span>Next &raquo;</span>
  {% endif %}
</div>
{% endif %}

Conclusion

Mastering the paginate tag in Shopify's Liquid templating language is a valuable skill for any theme developer or store owner looking to optimize their online store's user experience and performance. Remember, the paginate tag is just one tool in your Shopify arsenal. Combine it with other Liquid objects and filters to create a truly customized and user-friendly storefront.