An Easy Guide To Craft CMS Pagination

How Pagination Works in Craft CMS

Pagination Logic and Mechanics

Pagination in Craft CMS allows you to split a large number of entries across multiple pages. Under the hood, pagination uses the concepts of limits and offsets to determine which entries should be displayed on each page.

The entry query in Craft imposes a limit on the number of entries that can be returned. For example, if you set a limit of 10 entries, only the first 10 entries would be returned by the query initially. The offset then comes into play to return the next set of entries for the subsequent pages. If the offset was set to 10, the next page would return entries 11 to 20 from the total entry list.

By manipulating the limit and offset, you can effectively split the entries over n number of pages. Craft handles all the calculations automatically in the background. As a site builder, you simply define the desired limit per page, and Craft will take care of determining the required number of pages based on the total entries count.

The mechanics of pagination in Craft are quite straightforward once you grasp these core concepts of limits and offsets. Understand that a higher limit means fewer pages, while a lower limit results in more pages for the same set of entries. The offsets increment by the limit value to move the entry pointer ahead for each page.

The {% paginate %} Tag

The {% paginate %} tag in Twig templates is the primary way to output paginated pages in Craft CMS. This tag works hand-in-hand with entry queries to handle the display of entries across multiple pages.

Here is a typical example of how the paginate tag is used in a template:

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

{% for entry in entries %}

{{ entry.title }}

{% endfor %}

{% endpaginate %}

This tag paginates the blog entries by limiting each page to 10 entries. The paginated entries are stored in the entries variable which can then be looped through.

When {% paginate %} tag is used, Craft will automatically output the page navigation markup after the endpaginate tag. This includes previous/next links and page numbers based on the calculated pages.

Some key points about using paginate tag:

• It must be used with an entry query

• The limit defines the entries per page

• The paginated entries are stored in a variable for use in the template

• Craft outputs the page navigation markup automatically

So in a nutshell, the {% paginate %} tag handles all the heavy lifting of splitting entries across pages and outputting the navigation.

Calculating Pages

Craft CMS calculates the number of pages based on the total entries count and the limit defined per page. Here is the basic formula:

Total Pages = Ceiling (Total Entries / Limit)

For example, if you have 50 entries and a limit of 10 entries per page, the number of pages would be Ceiling(50/10) = Ceiling(5) = 5 pages.

The key things that affect the page calculations are:

• Total number of entries - more entries means more pages

• Limit per page - lower limit increases pages

Craft also accounts for edge cases where the entry count is not perfectly divisible by the limit. The Ceiling function ensures all entries are displayed across the calculated pages.

Understanding how pages are calculated helps when designing pagination for a site section. If you want to minimize pages, set a higher limit. If you want more granular pagination, lower the limit.

The number of pages also impacts the structure of the page navigation. More pages mean more page links and numbers to output. Craft handles outputting the optimal page navigation based on your pagination settings.

In summary, Craft CMS takes care of all the complex pagination calculations behind the scenes. The {% paginate %} tag makes it simple to output paginated entries in your templates with autogenerated page navigation. Configuring the limit appropriately gives you flexibility in controlling pagination for the best site visitor experience.

Benefits of Pagination in Craft CMS

Improved Performance

One of the biggest benefits of implementing pagination in Craft CMS is enhanced site performance. Displaying all entries on a single long page can cause slow load times and impact user experience.

Pagination optimizes performance by splitting content across multiple smaller pages that load much quicker. Less content per page means faster initial page loads and quicker delivery of information to users.

For example, displaying 50 blog posts on one page would result in a bloated, slow-loading page. Paginating those 50 posts into sets of 10 posts per page would improve load times 5x. Users get access to the content faster without slogging through a long page.

The performance gains are especially noticeable on lower-powered mobile devices. Quickly loading paginated pages keeps users engaged as they scroll through content seamlessly. Fewer entries per page also means lighter page weight, less images to load, and reduced server resource usage.

Overall, paginating content is one of the easiest and most effective ways to optimize site speed in Craft CMS. It lightens the load for both servers and clients. Users stay immersed in the experience rather than getting frustrated with endless scrolling of a mammoth page.

Better SEO

Pagination can also enhance a site's SEO by making pages more crawlable for search engines. One massive page with hundreds of entries would be difficult for search bots to crawl and index properly.

Splitting content over logically paginated pages gives search engines smaller chunks of related content to digest. This results in improved indexation and greater opportunity for search visibility.

Paginated pages also solve the issue of having a single enormously bloated page. Search engines generally recommend keeping pages under 2MB in size and under a few hundred kilobytes for optimal performance. Breaking up content into smaller pages prevents excessively heavy pages.

The page navigation provided by pagination also helps search bots navigate logically from page to page to discover and index all the content on a site. Pagination done right is clearly SEO-friendly.

Enhanced User Experience

Lastly, implementing thoughtful pagination enhances the overall user experience on a site built with Craft CMS. The performance gains and logical content splits provide a smoother, more engaging journey for site visitors.

Quickly loading pages keeps users focused on consuming content rather than waiting for endless page loads. Scanning content in shorter page segments is also easier on users rather than facing a never-ending scroll of information.

Well-structured pagination provides intuitive splits in content that make sense to users. For example, paginating blog posts by month or separating listings by categories into pages. This adds order to the content rather than displaying it randomly on a single crammed page.

The bottom line is pagination improves UX metrics from engagement and low bounce rates to click depth and pages per session. Users ultimately derive greater value from the content thanks to the enhanced discoverability and digestibility provided by pagination.

In summary, enabling pagination in Craft provides a triple benefit of better performance, SEO, and UX. All of this simply from splitting content over well-designed pages. For any sizable content, paginated pages should be a top priority for a polished Craft CMS site.

Setting Up Pagination in Craft CMS

Configuring Pagination

Setting up basic pagination in Craft CMS involves just a few simple steps:

1. Define the entry query to paginate, setting the desired limit per page

2. Add the {% paginate %} tag in your template

3. Output the paginated entries

4. Display the pagination links

Here is an example entry query to paginate blog posts with a limit of 10 per page:

{% set entries = craft.entries()

.section('blog')

.limit(10) %}

The limit of 10 here means each page will contain 10 blog post entries max.

Then in our template, we wrap this query with the {% paginate %} tag:

{% paginate entries as pageEntries %}

{% for entry in pageEntries %}

{{ entry.title }}

{% endfor %}

{{ paginate.prevUrl }}

{{ paginate.nextUrl }}

{% endpaginate %}

This paginates the entries into the pageEntries variable which we can loop through to output the entry titles.

The paginate.prevUrl and paginate.nextUrl output the previous/next pagination links. Craft handles generating the full pagination navigation including page numbers.

That's the basics of setting up pagination for an entry query in Craft! Adjust the limit to control the number of entries per page.

Linking Paginated Pages

When paginating across multiple pages, we need to properly link between the pages for navigation.

Within the paginate loop, reference the paginate variables to generate links:

<a href="{{ paginate.prevUrl }}">Previous Page</a>

<a href="{{ paginate.nextUrl }}">Next Page</a>

The paginate.prevUrl and paginate.nextUrl will automatically update based on the current paginated page being viewed.

To link to a specific page number, reference paginate.getPageUrl(pagenumber) like:

<a href="{{ paginate.getPageUrl(3) }}">Page 3</a>

This allows linking to any valid page number in the paginated pages.

Having proper links between the paginated pages allows users to seamlessly navigate your content.

Defining the Pagination Template

A common practice is to define a dedicated pagination template that displays your content with the {% paginate %} tag and links.

For example, _paginator.twig:

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

{% for entry in entries %}

{{ entry.title }}

{% endfor %}

{% include "_paginationlinks" %}

{% endpaginate %}

This pagination template paginates the blog entries and includes a _paginationlinks partial template to output the links.

Then in our main template we simply include the paginator template:

{% include 'paginator' %}

Some benefits of this approach:

• Keeps pagination logic centralized in one template file

• Easily reuse pagination on any template

• Change pagination settings in one place

The paginator template acts as a parent wrapper to display any content across paginated pages with all the necessary pagination links and navigation.

In summary, setting up pagination requires configuring your entry query, adding the {% paginate %} tag, outputting the entries, and linking between pages - all of which can be handled nicely in a dedicated pagination template.

Pagination for Entry Listings

Blogs, News, and Other Entries

Pagination is a very common technique implemented on listing pages for various entry types such as blogs, news sections, events, publications, case studies, and more. Essentially any section on a Craft CMS website that contains multiple entries which need to be displayed across multiple pages will benefit from pagination. The goal is to split a large list of entries into logical pages to enhance site performance and user experience.

For blogs, pagination by date or post title alphabetically are popular options to chunk blog posts into manageable portions. For news sections, pagination by month or year published makes sense in order to view stories chronologically. The key in any section is to pick a pagination scheme that is optimal for organizing that type of content in a way that helps users easily digest and navigate through the entries.

Site architects should evaluate what pagination approaches make the most sense for how users will want to scan and discover certain kinds of information when designing entry listings. Dates, names, categories, publication years, or other attributes can lend themselves nicely to different pagination schemes depending on the content type. Applying intuitive pagination aligned with overall site information architecture and IA principles helps keep users engaged as they explore entry listings and archives.

Example Implementation

To illustrate pagination for entry listings, here is some example code for a blog section in a Craft CMS template:

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

<h1>Blog</h1>

{% for entry in pageEntries %}

<h2>{{ entry.title }}</h2>

{{ entry.summary }}

{% endfor %}

{% include '_pagination' %}

{% endpaginate %}

This paginates the blog posts over pages with 10 entries per page maximum. We loop through the pageEntries variable to output the title and summary for each post. An include statement brings in a _pagination partial template to render the pagination links.

For a news section, pagination by month published provides a logical way to view stories chronologically:

{% paginate craft.entries.section('news').limit(10).orderBy('postDate desc') as pageEntries %}

<h1>News</h1>

{% for entry in pageEntries %}

<h2>{{ entry.title }}</h2>

<p>{{ entry.postDate|date('F Y') }}</p>

{% endfor %}

{% endpaginate %}

Here we order news stories by post date and paginate. Outputting the entry postDate formatted nicely gives clear monthly pagination.

Considerations by Section

When implementing pagination for different kinds of entry sections, there are a few considerations for choosing optimal schemes:

For blogs, date-based or alphabetical pagination are common options. Tag archives may need separate pagination to account for posts grouped by tag. Keeping related posts together across page boundaries is also advised.

For news sections, date-based pagination is often desired in order to view stories chronologically. Allowing site visitors to navigate by year, month, or defined categories is also useful.

Publication libraries benefit from pagination by publication year as well as alphabetically. Splitting by publication series makes sense for publications with defined sets.

Event listings should paginate upcoming versus past events separately, with chronological ordering important for date-based pagination.

Case studies can be paginated alphabetically by client name, while allowing filtering by client industry or other attributes.

In each case, the optimal pagination scheme depends on the nature of the content and what makes sense for users to browse and scan that type of information. Mixing additional filters, categories, and organization with intelligent pagination provides the best experience across entry listing pages and archives.

Pagination for Product Listings

Paginating Products

Implementing pagination can be very beneficial for splitting large ecommerce product catalogs across multiple pages in Craft Commerce stores. Displaying hundreds or thousands of products on a single listing page would create a bloated, slow-loading experience for site visitors.

Paginating products into sensible chunks improves overall site performance. It also enhances user experience by breaking products into more digestible pages that are easier to scan and search. Endless scrolling through an enormous product list tends to quickly tire users.

Thoughtful pagination schemes aligned to the information architecture and IA provide much better usability.

Some common approaches to paginate product listings include ordering alphabetically by product name, splitting by price range, organizing by product category, showcasing newest/recently added products, highlighting best-selling/most popular products, or grouping by brand or manufacturer. The goal is to choose logical pagination methods that fit both the IA and reflect how customers intuitively browse for products. Alphabetical or category-based pagination make good starting points. Ecommerce architects should think through what schemes make the most sense for aiding product discovery and navigation based on how their unique audience shops.

Example Code

Here is some sample code to paginate products alphabetically in Craft Commerce:

{% paginate craft.products.orderBy('title asc').limit(24) as paginatedProducts %}

{% for product in paginatedProducts %}

<h2>{{ product.title }}</h2>

{{ product.price | commerceCurrency(cart.currency) }}

{% endfor %}

{{ paginate.prevUrl }}

{{ paginate.nextUrl }}

{% endpaginate %}

We order products alphabetically, paginate with a limit of 24 per page, then loop through to output the product details. The paginate links allow easy navigation between pages.

To paginate by a specific category, we can do:

{% set category = craft.categories.group('products').slug('accessories') %}

{% paginate category.products.limit(24) as products %}

{# output products here #}

{% endpaginate %}

This paginates the products related to the “accessories” category.

Paginating Categories

When paginating product categories themselves, some tips include:

• Order categories alphabetically

• Allow viewing by top-level parent categories

• Paginate sub-categories under each parent category individually

• Display category product counts to inform pagination

For example:

{% set parentCat = craft.categories.group('products').slug('electronics') %}

{% paginate parentCat.children.limit(10) as subCats %}

{# output sub-category links here #}

{% endpaginate %}

This paginates sub-categories under the “electronics” parent category alphabetically.

Intelligently paginating both product categories and individual product listings provides multiple ways for shoppers to digest the catalog content. It's important to optimize pagination logic per the unique IA and how site visitors will search and navigate an ecommerce store. Keeping both user experience and SEO in mind should guide effective pagination schemes.

Custom Pagination Controls

Customizing the UI

Craft CMS gives developers tremendous control to customize the pagination user interface thanks to the flexibility of Twig templates and CSS. The default pagination output generated by Craft is very clean and minimal. However, with some template tweaks and styling adjustments, you can entirely transform the pagination components to match any desired designs.

Some ways to achieve custom UI pagination include overriding the default _pagination.twig partial template to change the markup structure, adding custom CSS classes to style elements, conditionally hiding certain pagination components, outputting additional page data like current page and total pages, and embedding the pagination in menu bars, sidebars, and other locations. The core pagination functionality is handled by Craft out of the box, but designers have full access to mold the UI display.

For example, adding custom classes provides handles for styling:

<div class="pagination-wrap">

{% include "_pagination" with {

prevClass: 'prev-btn',

nextClass: 'next-btn'

} %}

</div>

Now CSS can target .prev-btn and .next-btn to style those elements.

Styling the Components

Some examples of styling pagination components with CSS:

/* Page number links */

.pagination li a {

padding: 10px 15px;

border-radius: 2px;
}

/* Active current page */

.pagination li.active a {

background: #f2f2f2;

}

/* Previous/Next buttons */

.pagination .prev-btn,

.pagination .next-btn {

font-size: 18px;

font-weight: bold;

}

/* Ellipsis */

.pagination .ellipsis {

padding: 10px;

}

Designers can tweak link colours, active states, fonts, spacing, borders, backgrounds, and more. For JavaScript-powered UIs, manipulating classes provides control to animate and interact with pagination.

Creative Implementations

Some examples of unique, engaging pagination UIs include:

• Iconography for prev/next arrows

• Circular pagination dots

• Pagination rendered as image thumbnails

• "Load More" infinite scroll buttons

• Swipe gestures on touch devices

• Progress bars instead of page numbers

• Animated page transitions

Distinctive pagination aligned with brand identity can increase user engagement. For instance, travel sites may use airplane icons while real estate sites depict houses. Pagination placement also impacts UX - sidebars, sticky headers, overlays, etc. allow exploration.

In summary, although Craft provides fundamental pagination functionality out of the box, front-end developers have an open canvas to craft the UI with limitless creativity through templates and styling.