Bootstrap Pagination Documentation

Use this partial template to display pagination for a collection using the recommended bootstrap 5 pagination markup.

Check our the Pagination Demo for full working examples.

Display pagination links for a collection

Simply pass in the collection to display pagination for and the template will handle the rest! By default, links will use the page query parameter but you may customize that by passing in the page_param variable.

Display pagination for a collection of blogposts

{% include "/marketpath/bs5-paginate/_pagination.liquid" collection:posts %}

Display pagination for search results

{% search results request.query_params.q page:request.query_params['page'] %}
{% include "/marketpath/bs5-paginate/_pagination.liquid" collection:results %}

Customize the pagination query parameter

{% var page_param = 'searchpage' %}
{% search collection request.query_params.q page:request.query_params[page_param] %}
{% include "/marketpath/bs5-paginate/_pagination.liquid" %}

Return a 404 response code for empty collections

If you are attempting to load content past page 1 and there are no results, the pagination template will automatically set the response code to 404 - No results. You can disable this behavior by setting the disable_404_for_empty_collections variable to false.

Change the size

Change the size of the pagination links using the pagination_size variable. Valid values are sm (for small) and lg (for large).

Small links

{% include "/marketpath/bs5-paginate/_pagination.liquid" pagination_size:'sm' %}

Large links

{% include "/marketpath/bs5-paginate/_pagination.liquid" pagination_size:'lg' %}

Change the alignment

Change the horizontal positioning of the pagination links using the pagination_justify variable. Valid values are start (for left - reversed on RTL layouts), center, and end (for right - reversed on RTL layouts).

Align left (start)

{% include "/marketpath/bs5-paginate/_pagination.liquid" pagination_justify:'start' %}

Align center

{% include "/marketpath/bs5-paginate/_pagination.liquid" pagination_justify:'center' %}

Align right (end)

{% include "/marketpath/bs5-paginate/_pagination.liquid" pagination_justify:'end' %}

Adjust the number of links displayed

Adjust the number of links displayed using the max_pagination_links variable. Odd numbers typically work best since they allow for the same number of pages to be displayed to the left and right of the current page. This number includes the current page, but does NOT include the first, previous, next, and last links. The default is 11.

Display up to 100 pages at a time

{% include "/marketpath/bs5-paginate/_pagination.liquid" max_pagination_links:100 %}

Only display up to 7 pages at a time

{% include "/marketpath/bs5-paginate/_pagination.liquid" max_pagination_links:7 %}

Show and hide the beginning and ending controls

By default the first, previous, next, and last links will be displayed. If they are irrelevant (ie: because you are already on the first or last page) they will still be displayed but will be disabled and will be non-functional. To hide the first and last links, set the hide_first_and_last variable to true. To hide the previous and next links, set the hide_prev_and_next variable to true.

Hide first and last link

{% include "/marketpath/bs5-paginate/_pagination.liquid" hide_first_and_last:true %}

Hide previous and next link

{% include "/marketpath/bs5-paginate/_pagination.liquid" hide_prev_and_next:true %}

Putting it all together

Here are a few examples of how the pagination might be used. See the pagination demo for some more working examples.

Pull latest blog posts

{% var page_param = 'p' %}
{% blog_posts posts = limit:10 page:request.query_params[page_param] sort_by:'post_date' sort_direction:'desc' %}
{% include '/path/to/blog_feed_template.liquid' %}
{% include "/marketpath/bs5-paginate/_pagination.liquid" collection:posts %}

Search by query parameter

{% var pageparam = '__results_start__' %}
{% var limitparam = 'limit' %}
{% var limit = request.query_params[limitparam] | default: 30 | to_int %}
{% var page = request.query_params[pageparam] | default: 1 | to_int %}
{% search collection limit:limit page:page sort_by:'post_date' sort_direction:'desc' %}
{% include '/path/to/search_results.liquid' %}
{% include "/marketpath/bs5-paginate/_pagination.liquid" page_param:pageparam max_pagination_links:100 pagination_size:'sm' %}

Self-adjusting template

{% blog_posts posts = limit:10 page:request.query_params['page'] sort_by:'post_date' sort_direction:'desc' %}

{% include '/path/to/blog_feed_template.liquid' %}

{% if posts.total_pages > 1 %}
    {% var max_pagination_links = 1 %}
    {% var hide_prev_and_next = false %}
    {% var hide_first_and_last = true %}
    {% var pagination_size = 'lg' %}
    {% if posts.page > 1 %}
        {% if posts.total_pages > 101 %}
            {% set max_pagination_links = 99 %}
            {% set pagination_size = 'sm' %}
            {% var hide_prev_and_next = true %}
            {% var hide_first_and_last = false %}
        {% elsif posts.total_pages > 10 %}
            {% set max_pagination_links = posts.total_pages %}
            {% set pagination_size = 'sm' %}
            {% var hide_prev_and_next = true %}
        {% else %}
            {% set max_pagination_links = posts.total_pages %}
            {% set pagination_size = 'md' %}
        {% endif %}
    {% endif %}
    {% include "/marketpath/bs5-paginate/_pagination.liquid" collection:posts %}
{% endif %}