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

Name Description
Pager type Determines the pager type: Page numbers (and “Prev” / “Next” links), Result counts, a “Load more” button or a “Per page” box

“Page numbers” pager type

Name Description
Inner size The number of pages to display on each side of the current page.
Dots label The placeholder between the inner and outer pages (leave blank to hide). Note: this label is translatable with the facetwp_i18n hook.
Prev button label The “Prev” button label (leave blank to hide). Note: this label is translatable with the facetwp_i18n hook.
Next button label The “Next” button label (leave blank to hide). Note: this label is translatable with the facetwp_i18n hook.

“Result counts” pager type

Name Description
Count text (plural) The plural text. Available placeholders: [lower], [upper], [total], [page], [per_page], [total_pages]. Note: this text is translatable with the facetwp_i18n hook.
Count text (singular) The “Single result” text. Note: this text is translatable with the facetwp_i18n hook.
Count text (none) The “No results” text. Note: this text is translatable with the facetwp_i18n hook.

“Load more” pager type

Name Description
Load more text The button text. Note: this text is translatable with the facetwp_i18n hook.
Loading text The button loading text. Note: this text is translatable with the facetwp_i18n hook.

“Per page” pager type

Name Description
Default label Set the default dropdown label, or leave blank. Note: this label is translatable with the facetwp_i18n hook.
Per page options A comma-separated list of choices.
Optionally add a non-numeric choice, for example “Show all”, to be used to show all results.

Note: this “Show all” label text (or the label you give it) is translatable with the facetwp_i18n hook.

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 all the way to the top, but only after interacting with the pager facet:

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
            }, 500);
          }
        });
      })(jQuery);
    </script>
<?php } );

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 point with a class (.your-class) or id (#your-id).

add_action( 'wp_head', function() { ?>
    <script>
      (function($) {
        $(document).on('facetwp-loaded', function() {
          if (FWP.loaded) {
            $('html, body').animate({
              scrollTop: $('.facetwp-template').offset().top
            }, 500);
          }
        });
      })(jQuery);
    </script>
<?php } );

Scroll offset and speed

Other settings you can play with, besides where to scroll to, are the scroll offset and scroll speed.

If you want to fine-tune the exact position where the scrolling ends, a scroll offset can be added. 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 set to -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.

// 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);

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:

<?php echo FWP()->facet->pager_args['page']; ?>

Show “Per page” number:

<?php echo FWP()->facet->pager_args['per_page']; ?>

Show the total number of results:

<?php echo FWP()->facet->pager_args['total_rows']; ?>

Show the total number of pages:

<?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.

See also