Pager

Overview

The Pager facet type can be used to add several types of pagination.

It might seem a bit counter-intuitive that pagination can be added as a facet type, but just like any other facet type, a Pager facet can be added by making a new facet in the FacetWP admin interface.

Go to the Facets tab, click “add new”, choose “Pager” as Facet type, choose a pager type, set its options, and place it on your page with a shortcode.

Choose a pager type

A Pager facet can be used to display four different pager types. For each Pager facet you add, you have to choose one of these four pager types in the Pager facet’s options:

1. Page numbers (and “Prev” / “Next” links)
2. Result counts
3. A “Load more” button
4. A “Per page” box

Display multiple pager types on a page

For each pager type you want to display on a page, you need to add a separate Pager facet in the FacetWP admin interface, with the “Pager type” option set to its own type. So if you want to display Page numbers and Result counts and a Per page box, you need to make 3 separate Pager facets and place 3 different shortcodes on the page.

Display a pager type more than once on page

If you want to display page numbers (or any of the other pager types) twice (or more) on the same page, for example above and below your post listing, you can just use re-use the shortcode for that Pager facet and place it on the page twice.

Available options

Pager type

“Page numbers” pager type

“Result counts” pager type

“Load more” pager type

“Per page” pager type

How to add pagination scrolling

FacetWP is AJAX-based, meaning pagination happens without a full page reload. The trade-off is that the browser does not automatically scroll to the top of the page upon pagination. This can be achieved with a bit of custom JavaScript. A few examples:

Scroll on paging facet interaction

This example scrolls the page to the top of the page, but only after interacting with the Pager facet:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'wp_head', function() { ?>
  <script>
    (function($) {
      $(document).on('facetwp-refresh', function() {
        if ( FWP.soft_refresh == true  {
          FWP.enable_scroll = true;
        } else {
          FWP.enable_scroll = false;
        }
      });
      $(document).on('facetwp-loaded', function() {
        if (FWP.enable_scroll == true) {
          $('html, body').animate({
            scrollTop: 0 // Scroll to the top of the page
          }, 500);
        }
      });
    })(jQuery);
  </script>
<?php } );

If you want the page to scroll to the top of the results listing instead (the element with class facetwp-template, replace the scrollTop option with how it’s used in the next example:

Scroll on any facet interaction

This example scrolls after interaction with any facet, not only with the Pager facet. In this example we also specify a point to scroll to: the top of the div with class facetwp-template, which is the top of the results listing. You can specify any scroll target with a class (.your-class) or id (#your-id).

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'wp_head', function() { ?>
  <script>
    (function($) {
      $(document).on('facetwp-loaded', function() {
        if ( FWP.loaded ) { // Run only after the first page load
          $('html, body').animate({
            scrollTop: $('.facetwp-template').offset().top // Scroll to the top of the element with class "facetp-template"
          }, 500);
        }
      });
    })(jQuery);
  </script>
<?php } );

Scroll offset and duration

Other settings you can play with, besides the scroll target, are the scroll offset and scroll duration.

For example, if you have a sticky navigation bar taking up space at the top, without adjusting the scroll offset the scrolled results will disappear partly behind the sticky navigation bar. In the code example below, the scroll offset is adjusted with a value of -80, which makes the scroll end 80px above the point specified, leaving room for the navigation bar.

Combine the settings in the code below with the above full examples.

How to use custom jQuery code?
jQuery code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of your (child) theme's header.php file. You can also load it with a hook in your (child) theme's functions.php file, or in the Custom Hooks add-on. To load the code only on pages with facets, use the facetwp_scripts hook. To load it on all pages, use wp_head or wp_footer. Or you can use a code snippets plugin. Note that jQuery code needs the jQuery library loaded. If it is not already loaded, you can enable jQuery in FacetWP's settings. More info
// scrolls to a point that is 80px above the top of the div with class"facetwp-template":
$('html, body').animate({
  scrollTop: $('.facetwp-template').offset().top -80
}, 500);

// scrolls to top of the div with class 'facetwp-template' in 350 milliseconds:
$('html, body').animate({
  scrollTop: $('.facetwp-template').offset().top
}, 350);

See our tutorial about page scrolling for more code examples of how and when to scroll the page.

FacetWP and infinite scroll

We often get the question if FacetWP supports infinite scroll, added by for example WooCommerce or Elementor infinite scroll plugins.

FacetWP does not support infinite scroll, which is intentional.

This means that plugins that add any form of infinity load / infinite scroll will not work as expected.

The closest thing is the “load more” pager type of the Pager facet, which generates a “load more” button, working similar to infinite scroll.

The load more button and URL vars

The “load more” pager type of the Pager facet does not update URL vars. This means that if a user clicks the Back button to go back to the listing, the position in the pagination and the previously loaded items are lost.

This behaviour is intentional. Let’s say there are 20 items per page and the user click the “load more” button 5 times, this results in 100 total results on the page. They click to go to a result, then click the Back button. When that Back button is clicked, FacetWP would have to load all 100 items at once, straining the server.

We recommend sticking with the “normal” numbers-based pager type (or use target="_blank" to open results) unless you absolutely need a “load more” button.

Displaying raw pager data

You can display raw pager data using PHP within your template files.

Show page number:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
<?php echo FWP()->facet->pager_args['page']; ?>

Show “Per page” number:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
<?php echo FWP()->facet->pager_args['per_page']; ?>

Show the total number of results:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
<?php echo FWP()->facet->pager_args['total_rows']; ?>

Show the total number of pages:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
<?php echo FWP()->facet->pager_args['total_pages']; ?>

Pagination and WooCommerce

FacetWP has built-in support for WooCommerce pagination, so generally there is no need to use a Pager facet on shop pages.

A good reason to keep WooCommerce pagination is that you can keep your theme’s styling, while if you replace it with a Pager facet, you have to style the pagination to match your theme. But still you might want to to replace it, for example if you want to use a “Load more” Pager type.

Be aware that if you decide to keep WooCommerce pagination, you may need to apply some fixes to get pagination and result counts working properly, depending on your template.

If you decide to replace WooCommerce pagination with a Pager facet, make sure to read these pointers.

If you are using the WooCommerce Product Search plugin, you may see pagination issues using WooCommerce pagination or Pager facets, specifically on product category/term pages. This is a known incompatibility that has a workaround.

Translate the aria labels

If you have enabled FacetWP’s a11y setting in Settings > FacetWP > Settings, the “page numbers” Pager facet type will have three aria-label attributes in its code: “Go to page #”, “Go to next page” and “Go to previous page”.

These aria labels can be translated with the internationalization function __(), or with the WordPress gettext filter. The following example translates them to Dutch:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'gettext', function( $translated_text, $text, $domain ) {
  if ( 'fwp-front' == $domain ) {
    if ( 'Go to page' == $text ) {
      $translated_text = 'Ga naar pagina';
    }
    if ( 'Go to next page' == $text ) {
      $translated_text = 'Ga naar volgende pagina';
    }
    if ( 'Go to previous page' == $text ) {
      $translated_text = 'Ga naar vorige pagina';
    }
  }
  return $translated_text;
}, 10, 3 );

The Pager facet and SEO

If you are using a Pager facet for pagination on archive pages, be aware that the individual posts on the subsequent paged pages, and the paged pages themselves, will not be seen and indexed by search engines. The Pager facet’s <a> tags do not have href attributes with links that the search engine spider can follow. Also, users without JavaScript enabled will not be able to see and use any pagination on paged archives that you are using FacetWP on.

For SEO, this is not necessarily problematic, as long as all individual posts are reachable for the search engine spider through other archive pages on the site, like post-type archives and term archives. Another way to make sure all pages are found is by implementing a sitemap and pointing to it in your robots.txt file.

If you are concerned about the implications for SEO or accessibility of using the Pager facet’s AJAX-based pagination, read this section that lists a few possible approaches.

Fix duplicate results when using a Pager facet

If you are seeing duplicate posts in your listing while using a Pager/Load more facet, or a Sort facet, the cause is almost always the way the posts are ordered in the query, which is determined by the orderby query argument.

If results are ordered by a value that is the same (or empty) for multiple posts, or by a random value, MySQL does not have a fallback and will often sort erratically. For example, ordering by menu_order can be problematic, because it defaults to 0 if it is not explicitly set for each post.

In this tutorial you can read more about which scenarios can cause this to happen, and how to fix it quickly by adding a secondary, fallback sort order to the listing query.

Modify the pager links HTML output

If your Pager facet is set to display as page numbers, you can customize the HTML output of the pager links (the numbers, dots, and “Prev”/”Next” links) with the facetwp_facet_pager_link hook.

For example, you can add classes to specific links, or remove certain links.

See also

• Shortcodes Reference
• The facetwp-loaded event
• The facetwp-refresh event
• The facetwp_facet_pager_link hook
• How to scroll the page on facet interaction
• Using FacetWP with WooCommerce
• Using FacetWP with WooCommerce plugins
• Using FacetWP with Elementor
• Using the facetwp_i18n hook to translate facet labels and strings
• Accessibility Support
• The FacetWP URL
• How to prevent duplicate results
• The Sort facet type