Craft 3 Documentation

{% paginate %}

This tag makes it easy to paginate a set of elements across multiple pages.

{% paginate craft.entries.section('blog').limit(10) as pageInfo, pageEntries %}

{% for entry in pageEntries %}
    <article>
        <h1>{{ entry.title }}</h1>
        {{ entry.body }}
    </article>
{% endfor %}

{% if pageInfo.prevUrl %}<a href="{{ pageInfo.prevUrl }}">Previous Page</a>{% endif %}
{% if pageInfo.nextUrl %}<a href="{{ pageInfo.nextUrl }}">Next Page</a>{% endif %}

Paginated URLs will be identical to the first page’s URL, except that “/p_X_” will be appended to the end (where X is the page number), e.g. http://example.com/news/p2.

Tip: You can use the pageTrigger config setting to customize what comes before the actual page number in your URLs. For example you could set it to 'page/', and your paginated URLs would start looking like http://example.com/news/page/2.

Warning: Only a single {% paginate %} tag should be used per request.

Parameters #

The {% paginate %} tag has the following parameters:

Element criteria #

The first thing you pass into the {% paginate %} tag is an Element Query object, which defines all of the elements that should be paginated. Use the limit parameter to define how many elements should show up per page.

Warning: This parameter needs to be an actual ElementCriteriaModel object; not an array of elements. So don’t call all() on the object.

as #

Next up you need to type “as”, followed by one or two variable names:

The actual variable name(s) are up to you, however if you only specify one variable name here, the pageInfo variable will be called “paginate” by default.

Here’s what they get set to:

Showing the elements #

The {% paginate %} tag won’t actually output the current page’s elements for you – it will only give you an array of the elements that should be on the current page (referenced by the variable you defined in the as parameter.)

Following your {% paginate %} tag, you will need to loop through this page’s elements using a {% for %} tag.

{% paginate craft.entries.section('blog').limit(10) as pageEntries %}

{% for entry in pageEntries %}
    <article>
        <h1>{{ entry.title }}</h1>
        {{ entry.body }}
    </article>
{% endfor %}

The pageInfo variable #

The pageInfo variable (or whatever you’ve called it, or paginate by default) provides the following properties and methods:

The pageInfo variable gives you lots of options for building the pagination navigation that’s right for you. Here are a few common examples.

Previous/Next Page Links #

If you just want simple Previous Page and Next Page links to appear, you can do this:

{% paginate craft.entries.section('blog').limit(10) as pageInfo, pageEntries %}

{% if pageInfo.prevUrl %}<a href="{{ pageInfo.prevUrl }}">Previous Page</a>{% endif %}
{% if pageInfo.nextUrl %}<a href="{{ pageInfo.nextUrl }}">Next Page</a>{% endif %}

Note that we’re wrapping those links in conditionals because there won’t always be a previous or next page.

First/Last Page Links #

You can add First Page and Last Page links into the mix, you can do that too:

{% paginate craft.entries.section('blog').limit(10) as pageInfo, pageEntries %}

<a href="{{ pageInfo.firstUrl }}">First Page</a>
{% if pageInfo.prevUrl %}<a href="{{ pageInfo.prevUrl }}">Previous Page</a>{% endif %}
{% if pageInfo.nextUrl %}<a href="{{ pageInfo.nextUrl }}">Next Page</a>{% endif %}
<a href="{{ pageInfo.lastUrl }}">Last Page</a>

There’s no reason to wrap those links in conditionals since there will always be a first and last page.

Nearby Page Links #

If you want to create a list of nearby pages, perhaps surrounding the current page number, you can do that too!

{% paginate craft.entries.section('blog').limit(10) as pageInfo, pageEntries %}

<a href="{{ pageInfo.firstUrl }}">First Page</a>
{% if pageInfo.prevUrl %}<a href="{{ pageInfo.prevUrl }}">Previous Page</a>{% endif %}

{% for page, url in pageInfo.getPrevUrls(5) %}
    <a href="{{ url }}">{{ page }}</a>
{% endfor %}

<span class="current">{{ pageInfo.currentPage }}</span>

{% for page, url in pageInfo.getNextUrls(5) %}
    <a href="{{ url }}">{{ page }}</a>
{% endfor %}

{% if pageInfo.nextUrl %}<a href="{{ pageInfo.nextUrl }}">Next Page</a>{% endif %}
<a href="{{ pageInfo.lastUrl }}">Last Page</a>

In this example we’re only showing up to five page links in either direction of the current page. If you’d prefer to show more or less, just change the numbers that are passed into getPrevUrls() and getNextUrls(). You can also choose to not pass any number in at all, in which case all previous/next page URLs will be returned.